/* $RCSfile: oraxml.h $ $Date: 27-jul-2004.14:37:33 $
   Copyright (c) 1999, 2003, Oracle.  All Rights Reserved. 

  ########################################################################
  #  WARNING!!  This header is used to generate documentation directly!  #
  # exact structure and syntax of this file must be maintained properly  #
  #       in order for documentation to be produced automatically!       #
  ########################################################################

  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
                                             _       _           _       
    ___    _ __    __ _  __  __  _ __ ___   | |     | |__       (_)  ___ 
   / _ \  | '__|  / _` | \ \/ / | '_ ` _ \  | |     | '_ \      | | / __|
  | (_) | | |    | (_| |  >  <  | | | | | | | |  _  | | | |     | | \__ \
   \___/  |_|     \__,_| /_/\_\ |_| |_| |_| |_| (_) |_| |_|     |_| |___/
                                                                       
       _                                               _                _ 
    __| |   ___   _ __    _ __    ___    ___    __ _  | |_    ___    __| |
   / _` |  / _ \ | '_ \  | '__|  / _ \  / __|  / _` | | __|  / _ \  / _` |
  | (_| | |  __/ | |_) | | |    |  __/ | (__  | (_| | | |_  |  __/ | (_| |
   \__,_|  \___| | .__/  |_|     \___|  \___|  \__,_|  \__|  \___|  \__,_|
                 |_|                                                      

  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

                         oraxml.h HAS BEEN DEPRECATED

                 DO NOT WRITE ANY NEW CODE USING THIS INTERFACE

                         SEE xml.h FOR REPLACEMENT API

  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

   FILE 
     oraxml.h

   DESCRIPTION 
     DEPRECATED Public header for the Oracle XML parser

   PUBLIC FUNCTION(S) 
     Top-level parser APIs, plus DOM (1.0 and partial 2.0) and SAX APIs
*/
 
#ifndef ORAXML_ORACLE
# define ORAXML_ORACLE

#ifndef STDIO_ORACLE
# define STDIO_ORACLE
# include <stdio.h>
#endif

#ifndef ORASTRUC
# include <orastruc.h>
#endif

/*---------------------------------------------------------------------------
                     PUBLIC TYPES AND CONSTANTS
  ---------------------------------------------------------------------------*/

#define XML_TYPES

/* DATATYPE boolean - Basic TRUE/FALSE type
    The basic flag type, which has one of the values TRUE or FALSE.
*/
/* typedef int boolean; */

/* DATATYPE oratext - Character pointer (all encodings)
    The basic character-pointer type, used for all data encodings.  It
    should be cast as required, especially for Unicode strings, whose
    type will be lxuchar (2 byte).
*/
/* typedef unsigned char oratext; */

/* DATATYPE uword - Native unsigned word
    The basic unsigned scalar value, size depends on architecture.  Used
    primary for returning error codes.
*/
/* typedef unsigned int uword; */

#ifndef XML_ORACLE
# ifndef XMLCTX_DEFINED
#  define XMLCTX_DEFINED
/* DATATYPE xmlctx - XML parser context
    The XML parser's context.  Created by xmlinit and passed to most
    functions.
*/
struct xmlctx; typedef struct xmlctx xmlctx;
# endif

/* DATATYPE xslctx - XSL processor context
    The XSL processor's context.  Created by xslinit and passed to
    many XSLT functions.
*/
typedef struct xslctx xslctx;

/* DATATYPE xpctx - XPath context
    The XPath context.  Created by xpmakexpathctx and passed to most
    of the XPath functions.
*/
typedef struct xpctx xpctx;

/* DATATYPE xpexpr - XPath expression
    A parsed XPath expression, as returned by xpparsexpathexpr.
*/
typedef struct xpexpr xpexpr;

/* DATATYPE xpobj - XPath object
    An XPath object.  See xpobjtyp for the possible types.
*/
typedef struct xpobj xpobj;

/* DATATYPE xmlnode - DOM node
    A basic DOM node, could be any type.
*/
typedef struct xmlnode xmlnode;
typedef xmlnode xmlentnode;
typedef xmlnode xmlfragnode;
typedef xmlnode xmlentrefnode;
typedef xmlnode xmldocnode;
typedef xmlnode xmltextnode;
typedef xmlnode xmlcdatanode;
typedef xmlnode xmlcommentnode;
typedef xmlnode xmlattrnode;
typedef xmlnode xmlpinode;
typedef xmlnode xmlelemnode;
typedef xmlnode xmlnotenode;
typedef xmlnode xmldtdnode;
#endif

/* DATATYPE xpnset - XPath node-set
    An XPath node-set, as returned by xpgetnsetval.
*/
typedef struct xpnset xpnset;

/* DATATYPE xpnsetele - XPath node-set element
    An XPath node-set element.  See xpgetfirstnsetelem, xpgetnextnsetelem,
    and xpgetnsetelemnode.
*/
typedef struct xpnsetele xpnsetele;

/* DATATYPE xmlihdl - I/O input handle
    Input handle union, for user-specified input callbacks
*/
typedef union {
    void *ptr_xmlihdl;   /* generic pointer (cast as needed) */
    struct {
        int fd;          /* integral file descriptor */
        int fd2;         /* second file descriptor (FTP data proto) */
        int fd3;         /* third file descriptor (FTP actual data) */
    } fds_xmlihdl;
} xmlihdl;

/* DATATYPE xmlacctype - XML URI access types
    URI access methods.
*/
typedef enum {
    XMLACCESS_NONE   = 0, /* not specified */
    XMLACCESS_UNK    = 1, /* specified but unknown */
    XMLACCESS_FILE   = 2, /* filesystem access */
    XMLACCESS_HTTP   = 3, /* HTTP */
    XMLACCESS_FTP    = 4, /* FTP */
    XMLACCESS_GOPHER = 5, /* Gopher */
    XMLACCESS_ORADB  = 6, /* Oracle DB */
    XMLACCESS_STREAM = 7  /* user-defined stream */
} xmlacctype;
#define XMLACCESS_MAX 7 /* range is 0 to XMLACCESS_MAX */

/* DATATYPE xmldomimp - DOM implementation
    The DOMImplementation structure.  Returned by getImplementation and
    required by functions in the DOMImplementation interface.
*/
typedef struct xmldomimp xmldomimp;

/* DATATYPE xmlnodes - DOM NamedNodeMap/NodeList
    A list of nodes; the underlying implementation of NodeList and
    NamedNodeMap.
*/
typedef struct xmlnodes xmlnodes;

/* DATATYPE xsloutputmethod - XSL output method
    Choice of output method for XSL processing
*/
typedef enum {
    XSLMETHOD_UNKNOWN = 0,
    XSLMETHOD_XML,
    XSLMETHOD_TEXT,
    XSLMETHOD_HTML
} xsloutputmethod;

/* DATATYPE xpobjtyp - XPath object type
    XSL object types
*/
typedef enum xpobjtyp {
    XPOBJTYP_BOOL,   /* boolean */ 
    XPOBJTYP_NUM,    /* number */
    XPOBJTYP_STR,    /* string */
    XPOBJTYP_NSET,   /* node set */
    XPOBJTYP_RTFRAG  /* result tree fragment */
} xpobjtyp;

/* DATATYPE xmlflags - XML parser flags
    Flag bits for xmlparse functions.
*/
#define XML_FLAG_VALIDATE               0x01
#define XML_FLAG_DISCARD_WHITESPACE     0x02
#define XML_FLAG_DTD_ONLY               0x04
#define XML_FLAG_STOP_ON_WARNING        0x08
#define XML_FLAG_WARN_DUPLICATE_ENTITY  0x10
#define XML_FLAG_FORCE_INCODING         0x20
#define XML_FLAG_DONT_EXPAND_CHAR_REF   0x40
typedef ub4 xmlflags;

/* DATATYPE xmlpflags - XML printer flags
    Flag bits for print functions.
*/
#define XML_FLAG_PRINT_XMLDECL          0x01
typedef ub4 xmlpflags;

/* DATATYPE xmlntype - DOM node types
    Parse tree node types.  Names & values through #12 match DOM specification.
*/
#define ELEMENT_NODE                1  /* element */
#define ATTRIBUTE_NODE              2  /* attribute */
#define TEXT_NODE                   3  /* char data (not CDATA) */
#define CDATA_SECTION_NODE          4  /* char data (CDATA) */
#define ENTITY_REFERENCE_NODE       5  /* entity reference */
#define ENTITY_NODE                 6  /* entity */
#define PROCESSING_INSTRUCTION_NODE 7  /* <?pi?> */
#define COMMENT_NODE                8  /* <!-- Comments --> */
#define DOCUMENT_NODE               9  /* Document */
#define DOCUMENT_TYPE_NODE         10  /* DTD */
#define DOCUMENT_FRAGMENT_NODE     11  /* Document fragment */
#define NOTATION_NODE              12  /* notation */
#define ELEMENT_DECL_NODE          13  /* <!ELEMENT> declaration */
#define ATTR_DECL_NODE             14  /* <!ATTLIST> attr decl */
#define CP_ELEMENT_NODE            15  /* element */
#define CP_CHOICE_NODE             16  /* choice (a|b) */
#define CP_SEQUENCE_NODE           17  /* sequence (a,b) */
#define CP_PCDATA_NODE             18  /* #PCDATA */
#define CP_STAR_NODE               19  /* '*' (zero or more) */
#define CP_PLUS_NODE               20  /* '+' (one or more) */
#define CP_OPT_NODE                21  /* '?' (optional) */
typedef ub1 xmlntype;

/* forward declare */
struct xmlstream;
typedef struct xmlstream xmlstream;

/* obsolete, do not use */
#define XML_PRINTF(func) \
    boolean func(void *ctx, oratext *s, uword len)

/*---------------------------------------------------------------------------
                      ERROR CODES, XMLERR_xxx

                        0000 0099 Generic
                        0100 0199 VC and other Warnings
                        0200 0299 Parser
			0300 0399 XSL
			0400 0499 XPath

  ---------------------------------------------------------------------------*/

/* Errors in the following range are considered "warnings" and may continue */
#define XMLERR_WARN_MIN		100	/* minimum warning code */
#define XMLERR_WARN_MAX		199	/* maximum warning code */

#define XMLERR_OK               0       /* success return */
#define XMLERR_NULL_PTR         1       /* NULL pointer */
#define XMLERR_NO_MEMORY        2       /* out of memory */
#define XMLERR_HASH_DUP         3       /* duplicate entry in hash table */
#define XMLERR_INTERNAL         4       /* internal error */
#define XMLERR_BUFFER_OVERFLOW  5       /* name/quoted string too long */
#define XMLERR_INVALID_CHILD    6       /* invalid child for parent */
#define XMLERR_EOI              7       /* unexpected End Of Information */
#define XMLERR_INVALID_MEMCB    8       /* invalid memory callbacks */
#define XMLERR_UNICODE_ALIGN    12      /* Unicode data misalignment */
#define XMLERR_NODE_TYPE        13      /* wrong node type */
#define XMLERR_UNCLEAN          14      /* context is not clean */

/* Errors 50 99 are reserved for lpxinit errors and have no associated
   error messages since they are assumed to be due to errors made by the 
   caller. */
#define XMLERR_NLS_MISMATCH     50      /* specify both lxglo/lxd or neither*/
#define XMLERR_NLS_INIT         51      /* error during NLS initialization */
#define XMLERR_LEH_INIT         52      /* error during LEH initialization */

#define XMLERR_VC_ROOT_ELEM     100     /* root element mismatch */
#define XMLERR_VC_DECL_PE_NEST  101     /* improper decl/pe nesting */
#define XMLERR_VC_STDALONE_DOC  102     /* bogus standalone doc decl */
#define XMLERR_VC_INVALID_ELEM  103     /* invalid element (mismatch DTD) */
#define XMLERR_VC_UNDEF_ELEM    104     /* element is not defined */
#define XMLERR_VC_NOT_EMPTY     105     /* element should be empty */
#define XMLERR_VC_UNDEF_ATTR    106     /* undefined attribute */
#define XMLERR_VC_UNIQUE_ELEM   107     /* element multiply defined */
#define XMLERR_VC_GROUP_PE_NEST 108     /* improper group/pe nesting */
#define XMLERR_VC_DUP_TYPE      109     /* duplicate name in mixed decl */
#define XMLERR_VC_BAD_NAME      110     /* bad Name */
#define XMLERR_VC_BAD_NMTOKEN   111     /* bad Nmtoken */
#define XMLERR_VC_ONE_ID        112     /* multiple ID attributes */
#define XMLERR_VC_ID_ATTR_DEF   113     /* ID not IMPLIED or REQUIRED */
#define XMLERR_VC_ENUM          114     /* attr val not in enumeration */
#define XMLERR_VC_REQ_ATTR      115     /* missing required attribute */
#define XMLERR_VC_FIXED_ATTR    116     /* wrong val for fixed attribute */
#define XMLERR_VC_UNDEF_ENTITY  118     /* undefined entity */
#define XMLERR_VC_ENTITY_PARSE  119     /* entity attribute not unparsed */
#define XMLERR_VC_ENTITY_NDATA  120     /* undefined entity NDATA */
#define XMLERR_VC_UNDEF_NOTE    121     /* undefined notation */
#define XMLERR_VC_UNDEF_ID      122     /* undefined ID (in IDREF) */
#define XMLERR_VC_DUP_ID        123     /* duplicate ID */
#define XMLERR_VC_ATTR_REFS     124     /* attr value missing refs */
#define XMLERR_DUP_ENTITY       125     /* duplicate entity */

#define XMLERR_CONVERT          200     /* encoding conversion problem */
#define XMLERR_BAD_ENCODING     201     /* invalid encoding */
#define XMLERR_OPEN_FILE        202     /* could not open file */
#define XMLERR_READ_FILE        203     /* could not read from file */
#define XMLERR_SYNTAX           204     /* generic syntax error */
#define XMLERR_COMMENT_SYNTAX   205     /* comment syntax error */
#define XMLERR_CDATA_SYNTAX     206     /* CDATA syntax error */
#define XMLERR_COND_SYNTAX      207     /* conditional section syntax error */
#define XMLERR_DTD_KEYWORD      208     /* unknown keyword found in DTD */
#define XMLERR_XML_RESERVED     209     /* XML cannot be used in a PI */
#define XMLERR_NOT_EXPECTED     210     /* syntax error */
#define XMLERR_DEF_DECL         211     /* error in default declaration */
#define XMLERR_COMMENT_END      212     /* comment syntax error */
#define XMLERR_COMMENT_NOEND    213     /* comment syntax error */
#define XMLERR_CDATA_NOEND      214     /* CDATA syntax error */
#define XMLERR_PIDATA_NOEND     215     /* PIDATA syntax error */
#define XMLERR_INVALID_WIDE_CHAR    216 /* Invalid lxwchar */
#define XMLERR_INVALID_UNICODE_CHAR 217 /* Invalid lxuchar */
#define XMLERR_INVALID_NATIVE_CHAR  218 /* Invalid ASCII/EBCDIC character */
#define XMLERR_BAD_CHARREF      219     /* Invalid character */
#define XMLERR_CHARDATA         220     /* Error while processing text */
#define XMLERR_ATTR_VALUE       221     /* Invalid char in attribute value */
#define XMLERR_SAX              222     /* Error from SAX callback */
#define XMLERR_WFC_EXT_ENTITY   223     /* No external entity in attrib val */
#define XMLERR_WFC_UNIQUE_ATTR  224     /* Attributes must be unique */
#define XMLERR_WFC_ELEM_MATCH   225     /* Start tag and end tag of elem */
#define XMLERR_WFC_ENTITY_DECL  226     /* Entity not declared */
#define XMLERR_WFC_PARSED_ENT   227     /* Must be a parsed entity */
#define XMLERR_WFC_RECUR        228     /* No recursion in entity refs */
#define XMLERR_EMPTY_FILE       229     /* Empty file */
#define XMLERR_INVALID_NM_UNICODE_CHAR \
                                230     /* Invalid character in NAME/NMTOKEN */
#define XMLERR_INVALID_NM_NATIVE_CHAR \
                                231     /* Invalid character in NAME/NMTOKEN */
#define XMLERR_WFC_INVALID_PE   232     /* PE improperly used in internal DTD*/
#define XMLERR_NSC_LEADING_XML  233     /* Leading XML for namespace prefix */
#define XMLERR_NSC_PREFIX_DECL  234     /* Namespace prefix not declared */
#define XMLERR_BAD_VERSION      235     /* XML Version not supported */
#define XMLERR_INVALID_PUB_CHAR 236     /* Invalid pubid character */
#define XMLERR_COND_KEYWORD     237     /* condition section keyword invalid */
#define XMLERR_COND_UNFINISHED  238     /* condition is unfinished (open) */
#define XMLERR_ATTR_TYPE        239     /* invalid attribute type */
#define XMLERR_NWF_ELEM_START   240     /* element-start tag is NWF */
#define XMLERR_NWF_ENTREF       241     /* entity reference is NWF */
#define XMLERR_AMPERSAND        242     /* invalid use of ampersand char */
#define XMLERR_ATTR_QUOTE       243     /* elem attr value not in quotes */
#define XMLERR_LESSTHAN         244     /* invalid use of '<' character */
#define XMLERR_EXTRA_DATA       245     /* extra data at end of document */
#define XMLERR_NO_SYSID         246     /* missing SYSID after PUBID */
#define XMLERR_BAD_DTD          247     /* bad DTD declaration */
#define XMLERR_BAD_ENTITY_DECL  248     /* bad entity declaration */
#define XMLERR_BAD_EXTID        249     /* bad external ID declaration */
#define XMLERR_BAD_ATTR_DECL    250     /* bad attribute declaration */
#define XMLERR_INT_COND         251     /* no conditionals in internal DTD */
#define XMLERR_ENTITY_NESTING   252     /* improper entity nesting */
#define XMLERR_NO_VERSION       253     /* missing required version# */
#define XMLERR_BAD_XML_DECL     254     /* bad XML declaration */
#define XMLERR_STANDALONE_YN    255     /* invalid standalone yes/no */
#define XMLERR_ELEMENT_DECL     256     /* invalid element declaration */
#define XMLERR_CHILDREN_DECL    257     /* invalid children declaration */
#define XMLERR_MIXED_DECL       258     /* invalid mixed declaration */
#define XMLERR_NOTATION_DECL    259     /* invalid notation declaration */
#define XMLERR_XMLSPACE_DECL    260     /* invalid xml:space declaration */
#define XMLERR_INVALID_URL      261     /* invalid URL */
#define XMLERR_UNSUP_PROT       262     /* unsupported protocol */
#define XMLERR_OPEN_TCP         263     /* failed to open TCP connection */
#define XMLERR_SEND_TCP         264     /* failed to send to TCP connection */
#define XMLERR_RECV_TCP         265     /* failed to read from TCP conn. */
#define XMLERR_INVALID_LANG     266     /* invalid language specification */
#define XMLERR_RESOLVE_URL      267     /* couldn't resolve relative URL */
#define XMLERR_INVALID_ACCESS   268     /* invalid access method */
#define XMLERR_ACCESS_FUNCS     269     /* all access funcs must be provided */
#define XMLERR_FTP_CMD          270     /* FTP command failed */
#define XMLERR_FTP_LOGIN        271     /* FTP login failed */
#define XMLERR_FTP_UNAVAIL      272     /* FTP server unavailable */
#define XMLERR_INIT_TCP         273     /* failed to initialize TCP/IP */
#define XMLERR_CANT_IMPORT      274     /* can't import that node type */
#define XMLERR_CANT_SET_ENC     275     /* can't set output encoding */
#define XMLERR_BAD_HTTP_MIME    276     /* bad Mime header in HTTP reply */
#define XMLERR_END_QUOTE        277     /* No ending quote was seen */
#define XMLERR_INVALID_PROXY    278     /* Invalid protocol proxy */
#define XMLERR_INVALID_NO_PROXY 279     /* Invalid no-proxy specification */
#define XMLERR_HTTP_ERROR       280     /* HTTP protocol error */
#define XMLERR_UNSUP_ENCODING   281     /* unsupported encoding */
#define XMLERR_SHARED_DTD_MIX   282     /* doc can't have DTD if set shared */
#define XMLERR_WRONG_ENCODING   283     /* input document in wrong encoding */
#define XMLERR_NULL_URI         284	/* NULL URI in namespace pfx decl */

/* XSL error codes */

#define XMLERR_NONAMEINATTRSET           300   /* no name in attribute set */
#define XMLERR_ERROR_IN_XPATH            301   /* The XPATH function returns an
                                                  error */
#define XMLERR_CANNOT_TRANSFORM          302   /* The child node is of invalid
                                                  type or has invalid name */
#define XMLERR_ATTRIBUTE_NOT_EXPECTED    303   /* Attribute is found but its
                                                  value is not the expected
                                                  value */
#define XMLERR_NULL_INPUT_STRING         304   /* input string is null */
#define XMLERR_MISSING_TOKEN             305   /* expected token is missing */
#define XMLERR_INCOM_ATTR_VAL_TMPL       306   /* inputed string ended with no 
                                                  corresponding closing } */
#define XMLERR_NS_PREFIX_NOT_DECLARED    307   /* Namespace prefix used but not
                                                  not declared */
#define XMLERR_ATTRIBUTE_NOT_FOUND       308   /* The expected attribute for
                                                  this node is not found. */
#define XMLERR_CANNOT_INIT_XPATH         309   /* XPATH context could not be
                                                  initialized */
#define XMLERR_ELEMENT_NOT_FOUND         310   /* The expected element is not
                                                  found. */
#define XMLERR_FEATURE_NOT_SUPPORTED     311   /* feature not supported */
#define XMLERR_CANNOT_CONS_PI            312   /* The content of XML PI node
                                                  might be invalid. */
#define XMLERR_CANNOT_CONS_COMMENT       313   /* The content of XML comment
                                                  node might be invalid. */
#define XMLERR_FAIL                      314   /* An internal error occurred in
                                                  the code. */
#define XMLERR_EXT_FUNC_NOT_SUPPORTED    315   /* extension function not
                                                  supported */
#define XMLERR_INVALID_ATTR_VALUE        316   /* invalid value for attr */
#define XMLERR_UNDEF_DECIMAL_FORMAT      317   /* undefined decimal-format */
#define XMLERR_DUP_DEC_FORMAT            318   /* duplicate decimal-format */
#define XMLERR_INVALID_DATA              319   /* The data is not allowed */

#define XMLERR_OUTOFORDERATTRIBUTE       320   /* Cant add more attributes */
#define XMLERR_NULL_OUTPUT               321   /* No mechanism for output */
#define XMLERR_DOCUMENTNOTFOUND          322   /* Could not open doc */
#define XMLERR_APPLY_IMPORTS             323   /* Cant apply imports */
#define XMLERR_INV_LANG                  324   /* Invalid LANG for xsl:sort */

/* XPATH error codes */

#define XMLERR_XPATH_INTERNAL       400   /* Internal error */
#define XMLERR_XPATH_INVNAME        401   /* Invalid QName */
#define XMLERR_XPATH_INVAXIS        402   /* Invalid axis name */
#define XMLERR_XPATH_QTNOTMATCH     403   /* Unmatched quote */
#define XMLERR_XPATH_NSERR          404   /* Unable to resolve namespace */
#define XMLERR_XPATH_MEMERR         405   /* Unable to allocate memory */
#define XMLERR_XPATH_INVOBJTYP      406   /* Incorrect object type */
#define XMLERR_XPATH_NOTRSQB        407   /* Right square bracket missing */
#define XMLERR_XPATH_NOTRPAREN      408   /* Right parenthesis missing */
#define XMLERR_XPATH_INVTOK         409   /* Invalid token */
#define XMLERR_XPATH_VARREF         410   /* Unable to resolve the variable */
#define XMLERR_XPATH_UNKFUNC        411   /* Unknown function */
#define XMLERR_ENCODING_MISMATCH    412   /* encoding mismatch in Inc/Import*/

/* The range 470 499 are internal error codes. There would not be any error 
   mesgs corresponding to this in the mesg file. The error mesg given to the 
   user should be internal error. 
*/

#define XMLERR_XPATH_INVEXPRTREE    497   /* Invalid expression tree */
#define XMLERR_XPATH_INVOP          498   /* Invalid operator */
#define XMLERR_XPATH_INVCTX         499   /* Invalid context list/node */

/*---------------------------------------------------------------------------
                        Package Callback - User callback functions

    This package defines macros which declare functions (or function
    pointers) for XML callbacks.  Callbacks are used for error-message
    handling, memory allocation & freeing, and stream operations.

  ---------------------------------------------------------------------------*/

/****************************************************************************
			       Interface Callbacks
 ****************************************************************************/

/*---------------------------------------------------------------------------
    NAME
	XML_ALLOC [xmlmemcb]

    FUNCTION
	Memory allocation callback

    DESCRIPTION
	This macro defines a prototype for the low-level memory allocation
	function used in a xmlmemcb memory-callback structure.  If no memory
	callbacks are provided, malloc and free are used; if provided, the
	callbacks will be used instead.  Note allocated memory does not need
	to be initialized.

    RETURNS
        (void *) pointer to allocated memory [unitialized]

    ARGUMENTS
	ctx  (IN)  user-defined memory context
	size (OUT) number of bytes to allocate

    SEE ALSO
	xmlmemcb, xmlinit, xmlinitenc, XML_FREE
*/
#define XML_ALLOC(func) void *func(void *ctx, ub4 size)

/*---------------------------------------------------------------------------
    NAME
	XML_FREE [xmlmemcb]

    FUNCTION
	Memory freeing callback

    DESCRIPTION
	This macro defines a prototype for the low-level memory freeing
	function used in a xmlmemcb memory-callback structure.  If no
	memory callbacks are provided, malloc and free are used; if provided,
	the user's callbacks will be used instead.

    RETURNS
        (void)

    ARGUMENTS
	ctx (IN)  user-defined memory context
	ptr (OUT) pointer to memory to be freed

    SEE ALSO
	xmlmemcb, xmlinit, xmlinitenc, XML_ALLOC
*/
#define XML_FREE(func) void func(void *ctx, void *ptr)

/* DATATYPE xmlmemcb - Memory callbacks
    The parser allocates memory in large chunks, which are then doled
    out internally in small pieces.  The default system memory allocator
    (malloc, free) will be used to allocate and free the chunks unless a
    memory callback structure is provided.  To override the defaults, a
    xmlmemcb containing function pointers to alloc & free functions can
    be passed to xmlinit; the user's function will be used instead.  The
    memory callback context memcbctx is passed to the callback functions.
*/
struct xmlmemcb
{
    XML_ALLOC((*alloc));
    XML_FREE((*free));
};
typedef struct xmlmemcb xmlmemcb;

/*---------------------------------------------------------------------------
    NAME
	XML_OPENF [xmlaccess]

    FUNCTION
	I/O open callback

    DESCRIPTION
       This macro defines a prototype for the open function callback, which
       is called once to open the input source.  It should set its persistent
       handle in the xmlihdl union, which has two choices, a generic pointer
       (void *), and an integer (as Unix file or socket handle).  This function
       should return XMLERR_OK on success.  Args:

    RETURNS
        (uword) numeric error code, XMLERR_OK [0] on success

    ARGUMENTS
	ctx    (IN)  XML context
	path   (IN)  full path of the URI to be opened
	parts  (IN)  URI broken down into components (opaque pointer)
	length (OUT) total length of input data if known, 0 if not
	ih     (OUT) the opened handle is placed here

    SEE ALSO
	xmlaccess, XML_CLOSEF, XML_READF
*/
#define XML_OPENF(func) \
    uword func(xmlctx *ctx, oratext *path, void *parts, \
               ubig_ora *length, xmlihdl *ih)

typedef XML_OPENF((*xml_openf));

/*---------------------------------------------------------------------------
    NAME
	XML_CLOSEF [xmlaccess]

    FUNCTION
	I/O close callback

    DESCRIPTION
	This macro defines a prototype for the close function callback, called
	to close an open source and free its resources.  Args:

    RETURNS
	(void)

    ARGUMENTS
	ctx (IN) XML context
	ih  (IN) input handle union

    SEE ALSO
	xmlaccess, XML_OPENF, XML_READF
*/
#define XML_CLOSEF(func) \
    void func(xmlctx *ctx, xmlihdl *ih)

typedef XML_CLOSEF((*xml_closef));

/*---------------------------------------------------------------------------
    NAME
	XML_READF [xmlaccess]

    FUNCTION
	I/O read callback

    DESCRIPTION
	This macro defines a prototype for the read function callback, called
	to read data from an open source into a buffer, returning the number
	of bytes read: if 0, an EOI condition is indicated; if > 0, then the
	EOI flag determines if this is the final data.  On EOI, the matching
	close function will be called automatically.

    RETURNS
	(uword) number of bytes read [0 on EOI]

    ARGUMENTS
	ctx      (IN)  XML context
	path     (IN)  full URI of the open source (for error messages)
	ih       (IN)  input handle union
	dest     (OUT) destination buffer to read data into
	destsize (IN)  size of dest buffer
	nraw     (OUT) number of bytes read
	eoi      (OUT) End of Information? (last chunk of data)

    SEE ALSO
	xmlaccess, XML_OPENF, XML_CLOSEF
*/
#define XML_READF(func) \
    uword func(xmlctx *ctx, oratext *path, xmlihdl *ih, oratext *dest, \
               size_t destsize, sbig_ora *nraw, ub1 *eoi)

typedef XML_READF((*xml_readf));


/*---------------------------------------------------------------------------
    NAME
	XMLSTREAM_OPENF [xmlstream]

    FUNCTION
	Stream open callback

    DESCRIPTION
	Macro which defines the prototype for a stream open function.

    RETURNS
        (uword) error code, XMLERR_OK [0] for success

    ARGUMENTS
	stream (IN) stream descriptor
	rsvd   (IN) reserved for future use [must be 0]

    SEE ALSO
	xmlstream, XMLSTREAM_WRITEF, XMLSTREAM_CLOSEF, xslsetoutputstream,
	xslgetoutputstream
*/
#define XMLSTREAM_OPENF(func) \
    uword func(xmlstream *stream, ub4 rsvd)

/*---------------------------------------------------------------------------
    NAME
	XMLSTREAM_WRITEF [xmlstream]

    FUNCTION
	Stream write callback

    DESCRIPTION
	Macro which defines the prototype for a stream write function.

    RETURNS
        (uword) error code, XMLERR_OK [0] for success

    ARGUMENTS
	stream     (IN)  stream descriptor
	len        (IN)  number of bytes to write
	buf        (IN)  buffer to write
	lenwritten (OUT) bytes actually written
	rsvd       (IN)  reserved for future use [must be 0]

    SEE ALSO
	xmlstream, XMLSTREAM_OPENF, XMLSTREAM_CLOSEF, xslsetoutputstream,
	xslgetoutputstream
*/
#define XMLSTREAM_WRITEF(func) \
    uword func(xmlstream *stream, size_t len, oratext *buf, \
               size_t *lenwritten, ub4 rsvd)

/*---------------------------------------------------------------------------
    NAME
	XMLSTREAM_CLOSEF [xmlstream]

    FUNCTION
	Stream close callback

    DESCRIPTION
	Macro which defines the prototype for a stream close function.

    RETURNS
        (uword) error code, XMLERR_OK [0] for success

    ARGUMENTS
	stream     (IN)  stream descriptor
	rsvd       (IN)  reserved for future use [must be 0]

    SEE ALSO
	xmlstream, XMLSTREAM_OPENF, XMLSTREAM_WRITEF, xslsetoutputstream,
	xslgetoutputstream
*/
#define XMLSTREAM_CLOSEF(func) \
    uword func(xmlstream *stream, ub4 rsvd)

/*---------------------------------------------------------------------------*/

/* DATATYPE xmlstream - User-defined stream
    Generic user-defined stream object
*/
struct xmlstream {
    XMLSTREAM_OPENF((*open));
    XMLSTREAM_WRITEF((*write));
    XMLSTREAM_CLOSEF((*close));
    /* User can associate any data to xmlstream structure using this member
       so that he can access that inside the callbacks which will always
       have xmlstream as the first argument.  */
    void *userdata;
};

/*---------------------------------------------------------------------------
    NAME
	XML_MSGHDLRF [xmlinit]

    FUNCTION
	Error message handler

    DESCRIPTION
	This macro is used to define an error-message-handling function to
	be passed to xmlinit or xmlinitenc; if not defined, errors will be
	printed to stderr.

    RETURNS
        (void)

    ARGUMENTS
	msgctx  (IN) user-define message handler context
	msg     (IN) text of error message
	errcode (IN) numeric error code

    SEE ALSO
	xmlinit, xmlinitenc
*/
#define XML_MSGHDLRF(func) \
    void func(void *msgctx, const oratext *msg, uword errcode)

typedef XML_MSGHDLRF((*xml_msghdlr));

/*---------------------------------------------------------------------------
                           Package SAX - SAX APIs

    SAX is a standard interface for event-based XML parsing, developed
    collaboratively by the members of the XML-DEV mailing list.

    To use SAX, an xmlsaxcb structure is initialized with function
    pointers and passed to the xmlinit call. A pointer to a user-defined
    context structure may also be included; that context pointer will be
    passed to each SAX function.

  ---------------------------------------------------------------------------*/

#ifndef XMLSAXCB_DEFINED
# define XMLSAXCB_DEFINED

/****************************************************************************
			       Interface SAX
 ****************************************************************************/

/* SAX callback structure.  Set function pointers for those events you wish
   to receive, and make the rest NULL.  The entire structure should be
   initialized to zeros so that unused pointers at the end of the struct
   are NULL (to avoid future problems when they are defined to new events)

   All SAX functions return a (sword) error code.  A zero values means
   success and processing will continue; any non-zero value indicates a
   failure and parsing stops.

   Pointers passed to SAX callbacks (names, character data, etc), are only
   valid for the duration of the callback!  Once it has returned, the memory
   pointed to will be recycled and written over.  If you need to persistently
   keep the datums, you must copy them.
*/

struct xmlsaxcb
{
/*---------------------------------------------------------------------------
    NAME
        startDocument [SAX 1]

    FUNCTION
	Receives SAX start-of document notification

    DESCRIPTION
	The first SAX event, called once per document, indicating the
	start of the document.  Matching event is endDocument.

    EXAMPLE
	<?xml version="1.0"?>
	<top/>
	  -SAX->
	xmlDecl(version="1.0", encoding=NULL)
	startDocument()
	...

    RETURNS
        (sword) error code, XMLERR_OK [0] for success

    ARGUMENTS
        ctx (IN) user's SAX context [see xmlinit]

    SEE ALSO
	xmlinit, endDocument
*/
    sword (*startDocument)(void *ctx);

/*---------------------------------------------------------------------------
    NAME
        endDocument [SAX 1]

    FUNCTION
	Receives SAX end-of-document notification

    DESCRIPTION
	The last SAX event, called once per document, indicating the
	end of the document.  Matching event is startDocument.

    EXAMPLE
	<?xml version="1.0"?>
	<top/>
	  -SAX->
	xmlDecl(version="1.0", encoding=NULL)
	...
	endDocument()

    RETURNS
        (sword) error code, XMLERR_OK [0] for success

    ARGUMENTS
        ctx (IN) user's SAX context [see xmlinit]

    SEE ALSO
	xmlinit, startDocument
*/
    sword (*endDocument)(void *ctx);

/*---------------------------------------------------------------------------
    NAME
        startElement [SAX 1]

    FUNCTION
	Receives SAX start-of-element notification

    DESCRIPTION
	This event marks the start of an element.  Note this is the original
	SAX 1 non-namespace-aware version; startElementNS is the SAX 2
	namespace-aware version.  If both are registered, only the NS version
	will be called.  The element's name will be in the data encoding,
	as are all the attribute parts.  See the functions in the NamedNodeMap
	interface for operating on the attributes map.  The matching function
	is endElement (there is no endElementNS).

    EXAMPLE
	<?xml version="1.0"?>
	<top/>
	  -SAX->
	xmlDecl(version="1.0", encoding=NULL)
	...
	startElement(name="top", attrs=NULL)
	endElement(name="top")
	...

    RETURNS
        (sword) error code, XMLERR_OK [0] for success

    ARGUMENTS
        ctx   (IN) user's SAX context [see xmlinit]
	name  (IN) name of element [in data encoding]
	attrs (IN) NamedNodeMap of element's attributes, or NULL

    SEE ALSO
	xmlinit, endElement, getNodeMapLength, getNamedItem, getChildNode
*/
    sword (*startElement)(void *ctx, const oratext *name, 
                          const struct xmlnodes *attrs);

/*---------------------------------------------------------------------------
    NAME
        endElement [SAX 1]

    FUNCTION
	Receives SAX end-of-element notification

    DESCRIPTION
	This event marks the close of an element; it matches the startElement
	or startElementNS events.  The name is the tagName of the element
	(which may be a QName for namespace-aware elements) and is in the data
	encoding.

    EXAMPLE
	<?xml version="1.0"?>
	<top/>
	  -SAX->
	xmlDecl(version="1.0", encoding=NULL)
	...
	startElement(name="top", attrs=NULL)
	endElement(name="top")
	...

    RETURNS
        (sword) error code, XMLERR_OK [0] for success

    ARGUMENTS
        ctx  (IN) user's SAX context [see xmlinit]
	name (IN) name of ending element [in data encoding]

    SEE ALSO
	xmlinit, endElement
*/
    sword (*endElement)(void *ctx, const oratext *name);

/*---------------------------------------------------------------------------
    NAME
        characters [SAX 1]

    FUNCTION
	Receives SAX notification of character data

    DESCRIPTION
	This event marks character data, either Text or CDATA.  If a cdata
	callback is provided, then CDATA will be send to that instead; with
	no cdata callback, both Text and CDATA go to the characters callback.
	The data will be in the data encoding, and the returned length is in
	characters, not bytes.  See also ignorableWhitespace, which receiving
	notification about ignorable (whitespace formatting) character data.

    EXAMPLE
	<?xml version="1.0"?>
	<top>junk</top>
	  -SAX->
	xmlDecl(version="1.0", encoding=NULL)
	...
	characters(ch="junk", len=4)
	...

    RETURNS
        (sword) error code, XMLERR_OK [0] for success

    ARGUMENTS
        ctx (IN) user's SAX context [see xmlinit]
	ch  (IN) pointer to data [in data encoding]
	len (IN) length of data [in characters]

    SEE ALSO
	xmlinit, ignorableWhitespace
*/
    sword (*characters)(void *ctx, const oratext *ch, size_t len);

/*---------------------------------------------------------------------------
    NAME
        ignorableWhitespace [SAX 1]

    FUNCTION
	Receives SAX notification of ignorable (whitespace) data

    DESCRIPTION
	This event marks ignorable whitespace data such as newlines, and
	indentation between lines.  The matching function is characters,
	which receives notification of normal character data.  The data
	is in the data encoding, and the returned length is in characters,
	not bytes.

    EXAMPLE
	<?xml version="1.0"?>
	<top>
	    <sub>junk</sub>
	</top>
	  -SAX->
	xmlDecl(version="1.0", encoding=NULL)
	...
	startElement(name="top", attrs=NULL)
	ignorableWhitespace(ch="\n    ", len=5)
	startElement(name="sub", attrs=NULL)
	...

    RETURNS
        (sword) error code, XMLERR_OK [0] for success

    ARGUMENTS
        ctx (IN) user's SAX context [see xmlinit]
	ch  (IN) pointer to data [in data encoding]
	len (IN) length of data [in characters]

    SEE ALSO
	xmlinit, characters
*/
    sword (*ignorableWhitespace)(void *ctx, const oratext *ch, size_t len);

/*---------------------------------------------------------------------------
    NAME
        processingInstruction [SAX 1]

    FUNCTION
	Receives SAX notification of a processing instruction

    DESCRIPTION
	This event marks a processing instruction.  The PI's target and
	data will be in the data encoding.  There is always a target, but
	the data may be NULL.

    EXAMPLE
	<?xml version="1.0"?>
	<?keywords sax example?>
	<top/>
	  -SAX->
	xmlDecl(version="1.0", encoding=NULL)
	processingInstruction(target="keywords", data="sax example")
	...

    RETURNS
        (sword) error code, XMLERR_OK [0] for success

    ARGUMENTS
        ctx    (IN) user's SAX context [see xmlinit]
	target (IN) PI's target [in data encoding]
	data   (IN) PI's data [in data encoding] or NULL

    SEE ALSO
	xmlinit
*/
    sword (*processingInstruction)(void *ctx, const oratext *target, 
                                   const oratext *data);

/*---------------------------------------------------------------------------
    NAME
        notationDecl [SAX 1]

    FUNCTION
	Receives SAX notification of a notation declaration

    DESCRIPTION
	The even marks the declaration of a notation in the DTD.  The
	notation's name, public ID, and system ID will all be in the
	data encoding.  Both IDs are optional and may be NULL.

    EXAMPLE
	<?xml version="1.0"?>
	<!DOCTYPE foo [
	    <!NOTATION foo PUBLIC "[" "null.ent">
	]>
	...
	  -SAX->
	xmlDecl(version="1.0", encoding=NULL)
	notationDecl(name="foo", publicID="[", systemID="null.ent")

    RETURNS
        (sword) error code, XMLERR_OK [0] for success

    ARGUMENTS
        ctx      (IN) user's SAX context [see xmlinit]
	name     (IN) notation's name [in data encoding]
	publicID (IN) notation's public ID [in data encoding] or NULL
	systemID (IN) notation's system ID [in data encoding] or NULL

    SEE ALSO
	xmlinit
*/
    sword (*notationDecl)(void *ctx, const oratext *name, 
                          const oratext *publicId, const oratext *systemId);

/*---------------------------------------------------------------------------
    NAME
        unparsedEntityDecl [SAX 1]

    FUNCTION
	Receives SAX notification of a unparsed entity declaration

    DESCRIPTION
	Marks an unparsed entity declaration in the DTD; see parsedEntityDecl
	for parsed entity notification.  The unparsed entity's name,
	public ID, system ID, and notation name will all be in the data
	encoding.

    EXAMPLE
	<?xml version="1.0"?>
	<!DOCTYPE foo [
	    <!ENTITY e PUBLIC "p-p-pub-id" 'entity.dat' NDATA endayta>
	]>
	...
	  -SAX->
	xmlDecl(version="1.0", encoding=NULL)
	unparsedEntityDecl(name="e", publicID="p-p-pub-id",
	                   systemID="entity.dat", notationName="endayta")

    RETURNS
        (sword) error code, XMLERR_OK [0] for success

    ARGUMENTS
        ctx          (IN) user's SAX context [see xmlinit]
	name         (IN) entity's name [in data encoding]
	publicID     (IN) entity's public ID [in data encoding] or NULL
	systemID     (IN) entity's system ID [in data encoding]
	notationName (IN) entity's notation name [in data encoding]

    SEE ALSO
	xmlinit, parsedEntityDecl
*/
    sword (*unparsedEntityDecl)(void *ctx, const oratext *name, 
                                const oratext *publicId,
                                const oratext *systemId, 
                                const oratext *notationName);

/*---------------------------------------------------------------------------
    NAME
        nsStartElement [SAX 2]

    FUNCTION
	Receives SAX namespace-aware start-of-element notification

    DESCRIPTION
	This event marks the start of an element.  Note this is the new
	SAX 2 namespace-aware version; startElement is the SAX 1
	non-namespace-aware version.  If both are registered, only the NS
	version will be called.  The element's QName, local name, and
	namespace URI will be in the data encoding, as are all the attribute
	parts.  See the functions in the NamedNodeMap interface for
	operating on the attributes map.  The matching function is
	endElement (there is no endElementNS).

    EXAMPLE
	<?xml version="1.0"?>
	<foo:top xmlns:foo="/foo/bar"/>
	  -SAX->
	xmlDecl(version="1.0", encoding=NULL)
	...
	startElement(qname="foo:top", local="top", nsp="/foo/bar", attrs=NULL)
	endElement(name="foo:top")
	...

    RETURNS
        (sword) error code, XMLERR_OK [0] for success

    ARGUMENTS
        ctx   (IN) user's SAX context [see xmlinit]
	qname (IN) element's qualified name [in data encoding]
	local (IN) element's namespace local name [in data encoding]
	nsp   (IN) element's namespace URI [in data encoding]
	attrs (IN) NamedNodeMap of element's attributes, or NULL

    SEE ALSO
	xmlinit, startElement
*/
    sword (*nsStartElement)(void *ctx, const oratext *qname, 
                            const oratext *local, const oratext *nsp,
                            const struct xmlnodes *attrs);

/*---------------------------------------------------------------------------
    NAME
        comment [SAX 2]

    FUNCTION
	Receives SAX notification of a comment

    DESCRIPTION
	This event marks a comment in the XML document.  The comment's data
	will be in the data encoding.

    EXAMPLE
	<?xml version="1.0"?>
	<!--Just a comment-->
	<foo/>
	  -SAX->
	xmlDecl(version="1.0", encoding=NULL)
	comment(data="Just a comment")
	...

    RETURNS
        (sword) error code, XMLERR_OK [0] for success

    ARGUMENTS
        ctx  (IN) user's SAX context [see xmlinit]
	data (IN) comment's data [in data encoding]

    SEE ALSO
	xmlinit
*/
    sword (*comment)(void *ctx, const oratext *data);

/*---------------------------------------------------------------------------
    NAME
        elementDecl [SAX X]

    FUNCTION
	Receives SAX notification of an element's declaration

    DESCRIPTION
	This event marks an element declaration in the DTD.  The element's
	name and content will be in the data encoding.

    EXAMPLE
	<?xml version="1.0"?>
	<!DOCTYPE foo [
	    <!ELEMENT e (#PCDATA)>
	]>
	...
	  -SAX->
	xmlDecl(version="1.0", encoding=NULL)
	elementDecl(name="e", content="(#PCDATA)")
	...

    RETURNS
        (sword) error code, XMLERR_OK [0] for success

    ARGUMENTS
        ctx     (IN) user's SAX context [see xmlinit]
	name    (IN) element's name
	content (IN) element's context model

    SEE ALSO
	xmlinit, attributeDecl
*/
    sword (*elementDecl)(void *ctx, const oratext *name,const oratext *content);

/*---------------------------------------------------------------------------
    NAME
        attributeDecl [SAX X]

    FUNCTION
	Receives SAX notification of an attribute's declaration

    DESCRIPTION
	This event marks an element declaration in the DTD.  The element's
	name and content will be in the data encoding.  Note that an
	attribute may be declared before the element it belongs to!

    EXAMPLE
	<?xml version="1.0"?>
	<!DOCTYPE foo [
	    <!ATTLIST a id ID #IMPLIED>
	]>
	...
	  -SAX->
	xmlDecl(version="1.0", encoding=NULL)
	attributeDecl(elem="a", name="id", body="ID #IMPLIED")
	...

    RETURNS
        (sword) error code, XMLERR_OK [0] for success

    ARGUMENTS
        ctx  (IN) user's SAX context [see xmlinit]
	elem (IN) element that attribute is declared for [in data encoding]
	attr (IN) attribute's name [in data encoding]
	body (IN) body of attribute declaration [in data encoding]

    SEE ALSO
	xmlinit, attributeDecl
*/
    sword (*attributeDecl)(void *ctx, const oratext *elem,
                           const oratext *attr, const oratext *body);

/*---------------------------------------------------------------------------
    NAME
        xmlDecl [SAX X]

    FUNCTION
	Receives SAX notification of an XML declaration

    DESCRIPTION
	This event marks an XML declaration (XMLDecl).  The startDocument
	event is always first; if this callback is registered and an XMLDecl
	exists, it will be the second event.  The encoding flag says whether
	an encoding was specified.  Since the document's own encoding
	specification may be overridden, and the input will be converted to
	the data encoding anyway, the actual encoding specified is not
	provided.  getEncoding returns the name of the data encoding.  For
	the standalone flag, -1 will be returned if it was not specified,
	otherwise 0 for FALSE, 1 for TRUE.

    EXAMPLE
	<?xml version="1.0"?>
	<top/>
	  -SAX->
	xmlDecl(version="1.0", encoding=FALSE)
	...

    RETURNS
        (sword) error code, XMLERR_OK [0] for success

    ARGUMENTS
        ctx        (IN) user's SAX context [see xmlinit]
	version    (IN) version string from XMLDecl [in data encoding]
	encoding   (IN) encoding was specified?
	standalone (IN) value of standalone-document flag [< 0 not specified]

    SEE ALSO
	xmlinit, getEncoding
*/
    sword (*xmlDecl)(void *ctx, const oratext *version,
                     boolean encoding, sword standalone);

/*---------------------------------------------------------------------------
    NAME
        cdata [SAX 1]

    FUNCTION
	Receives SAX notification of CDATA

    DESCRIPTION
	This event marks CDATA, as distinct from Text.  If no CDATA
	callback is provided, the Text callback will be invoked.  The
	data will be in the data encoding, and the returned length is
	in characters, not bytes.  See also ignorableWhitespace, which
	receiving notification about ignorable (whitespace formatting)
	character data.

    EXAMPLE
	<?xml version="1.0"?>
	<doc><![CDATA [ stuff]]></doc>
	  -SAX->
	xmlDecl(version="1.0", encoding=NULL)
	...
	cdata(ch=" stuff", len=6)
	...

    RETURNS
        (sword) error code, XMLERR_OK [0] for success

    ARGUMENTS
        ctx (IN) user's SAX context [see xmlinit]
	ch  (IN) pointer to CDATA [in data encoding]
	len (IN) length of CDATA [in characters]

    SEE ALSO
	xmlinit, ignorableWhitespace
*/
    sword (*cdata)(void *ctx, const oratext *ch, size_t len);

/*---------------------------------------------------------------------------
    NAME
	parsedEntityDecl

    FUNCTION
	Receives SAX notification of a parsed entity declaration

    STATUS
	SAX 1

    DESCRIPTION
	Marks an parsed entity declaration in the DTD.  The parsed entity's
	name, public ID, system ID, and notation name will all be in the
	data encoding.

    EXAMPLE
	<?xml version="1.0"?>
	<!DOCTYPE foo [
	    <!ENTITY e1 "foobar">
	    <!ENTITY e2 SYSTEM "nop.ent">
	    <!ENTITY % e3 "parameter_entity_value">
	]>
	...
	  -SAX->
	xmlDecl(version="1.0", encoding=NULL)
	parsedEntityDecl(name="e1", value="foobar", pubID=NULL, sysID=NULL,
			general=TRUE)
	parsedEntityDecl(name="e2", value=NULL, pubID=NULL, sysID="nop.ent",
			general=TRUE)
	parsedEntityDecl(name="e3", value="parameter_entity_value",
			pubID=NULL, sysID=NULL, general=FALSE)

    RETURNS
	(sword) error code, XMLERR_OK [0] for success

    ARGUMENTS
	ctx     (IN) user's SAX context [see xmlinit]
	name    (IN) entity's name [data encoding]
	value   (IN) entity's value if internal [data encoding]
	pubId   (IN) entity's public ID [data encoding] or NULL
	sysId   (IN) entity's system ID [data encoding]
	general (IN) general entity?  parameter entity if FALSE.

    SEE ALSO
	unparsedEntityDecl
*/
    sword (*parsedEntityDecl)(void *ctx, const oratext *name,
			      const oratext *value, const oratext *pubId,
			      const oratext *sysId, boolean general);

/* The following 2 fields are reserved for future use. */
   void (*empty1)();
   void (*empty2)();
};

typedef struct xmlsaxcb xmlsaxcb;

#endif /* ifndef XMLSAXCB_DEFINED */

/*---------------------------------------------------------------------------
                      Package Parser - Top-Level APIs

    This C implementation of the XML processor (or parser) follows the W3C
    XML specification (rev REC-xml-19980210) and implements the required
    behavior of an XML processor in terms of how it must read XML data and
    the information it must provide to the application.

  ---------------------------------------------------------------------------*/

/****************************************************************************
			   Interface XMLParser
 ****************************************************************************/

/*---------------------------------------------------------------------------
    NAME
	xmlinit [DOM X]

    FUNCTION
	Initializes XML parser

    DESCRIPTION
        Initializes the C XML parser and returns a new parser context.  Must
	be called before any parsing can take place.  If this call is not
	successful, do not call any other XML parser functions!

	xmlinitenc is the same as xmlinit except that the DOM/SAX data
	encoding may be specified.  For xmlinit, the data encoding will match
	that of the first document parsed.

	This function should only be called once before parsing any XML files.
	xmlterm should be called after all parsing and DOM use has completed.
	Multiple parses should call xmlclean between runs if only the current
	document needs to be available.  Until clean is called, data pointers
	from all previous parses will continue to be valid.

	All arguments may be NULL except for err, which is required.  On
	success, an XML context (xmlctx *) is returned.  If this is NULL, a
	failure occurred: the error code is stored in *err, and depending
	on how far along in the initialization it got, an error message may
	be produced.

	DATA ENCODING: The encoding of input documents is detected
	automatically (by BOM, XMLDecl, etc).  If the encoding cannot be
	determined, 'incoding' is assumed.  If 'incoding' is not specified
	(NULL), UTF-8 is assumed.  'incoding' should be an IANA/Mine
	encoding name, e.g. "UTF-16", "ASCII", etc.

	The presentation encoding (via DOM/SAX) is automatically set to the
	encoding of the first document parsed.  See also the xmlinitenc
	function, which allows the data encoding to explicitly set.

	DOM vs SAX: By default, a DOM parse tree is built.  To use SAX
	instead, specify a SAX callback structure (saxcb); the presence of
	the callback struct acts as a flag.  The callbacks will be invoked
	with the given SAX context pointer.  If any of the SAX functions
	returns a non-zero error code, parsing stops immediately.

	ERROR MESSAGES: By default, error messages are printed to stderr.  To
	handle messages yourself, specify a handler function pointer.  The
	formatted error string and numeric error code will be passed to your
	function, along with the user-defined message context msgctx.  The
	error strings will be UTF-8; any data included as part of the error
	message will be converted to UTF-8.  The location where an error
	occurred may be fetched with the xmlwhere function.  The error
	handler function should be declared with the XML_MSGHDLRF function
	prototype macro.

	ERROR LANGUAGE: The error language is specified as lang, e.g.
	"AMERICAN", JAPANESE", "FRENCH", etc, and defaults to American.

	PERFORMANCE: A separate, fast code path exists for single-byte
	encodings (ASCII, ISO-8859, EBCDIC, etc).  This path is considerably
	faster than the multibyte and Unicode paths, so if you are sure your
	input documents are single-byte, you are strongly encouraged to tell
	the parser by setting the 'incoding' hint properly.

	Since all multibyte/Unicode inputs are converted to UTF-16 internally
	for homogenization, choosing UTF-16 output is next fastest since no
	extra conversion is needed.  The slowest code path is multibyte input
	with multibyte output, since there is a round trip to UTF-16 between.

    RETURNS
        (xmlctx *) XML context or NULL

    ARGUMENTS
        err       (OUT) Numeric error code, XMLERR_OK [0] on success
        incoding  (IN)  Default input encoding [in compiler encoding]
        msghdlr   (IN)  Error message handler function
        msgctx    (IN)  Context for the error message handler
        saxcb     (IN)  SAX callback structure filled with function pointers
        saxcbctx  (IN)  Context for SAX callbacks
        memcb     (IN)  Memory function callbacks
        memcbctx  (IN)  Context for the memory function callbacks
        lang      (IN)  Language for error messages [in compiler encoding]

    SEE ALSO
	xmlinitenc, xmlclean, xmlterm, xmlmemcb
*/
xmlctx *xmlinit(uword *err, const oratext *incoding,
                XML_MSGHDLRF((*msghdlr)), void *msgctx,
                const xmlsaxcb *saxcb, void *saxcbctx, 
                const xmlmemcb *memcb, void *memcbctx,
                const oratext *lang);

/*---------------------------------------------------------------------------
    NAME
	xmlinitenc [DOM X]

    FUNCTION
	Initalizes XML parser (specifying data encoding)

    DESCRIPTION
        Initializes the C XML parser and returns a new parser context.  Details
	are the same as for xmlinit except that an additional argument is
	supplied: the data encoding.  All DOM and SAX data will be presented
	in the given data encoding.  See the documentation for xmlinit.

    RETURNS
        (xmlctx *) XML context or NULL

    ARGUMENTS
        err       (OUT) Numeric error code, XMLERR_OK [0] on success
        incoding  (IN)  Default input encoding [in compiler encoding]
        outcoding (IN)  Output [DOM/SAX data] encoding [in compiler encoding]
        msghdlr   (IN)  Error message handler function
        msgctx    (IN)  Context for the error message handler
        saxcb     (IN)  SAX callback structure filled with function pointers
        saxcbctx  (IN)  Context for SAX callbacks
        memcb     (IN)  Memory function callbacks
        memcbctx  (IN)  Context for the memory function callbacks
        lang      (IN)  Language for error messages [in compiler encoding]

    SEE ALSO
	xmlinit, xmlclean, xmlterm, xmlmemcb
*/
xmlctx *xmlinitenc(uword *err, const oratext *incoding,
                               const oratext *outcoding,
                   XML_MSGHDLRF((*msghdlr)), void *msgctx,
                   const xmlsaxcb *saxcb, void *saxcbctx, 
                   const xmlmemcb *memcb, void *memcbctx,
                   const oratext *lang);

/*---------------------------------------------------------------------------
    NAME
        xmlterm [DOM X]

    FUNCTION
	Terminates XML parser

    DESCRIPTION
        Terminates (shuts down) the XML parser.  It should be called after
	xmlinit, and before exiting the main program.

        All allocated memory is freed, giving it back to the system (through
	free or the user's memory callback).  Contrast to xmlclean, which
	recycles memory internally without giving it back to the system.

        No additional XML parser calls can be made until xmlinit is called
	again to get a new context.

    RETURNS
        (uword) numeric error code, XMLERR_OK [0] on success

    ARGUMENTS
        ctx (IN) XML context

    SEE ALSO
	xmlinit, xmlinitenc, xmlclean
*/
uword xmlterm(xmlctx *ctx);

/*---------------------------------------------------------------------------
    NAME
        xmlclean [DOM X]

    FUNCTION
	Cleans up an XML context between parses

    DESCRIPTION
	Recycles memory within the XML parser, but does not free it to the
	system-- only xmlterm finally releases all memory back to the
	system.  If xmlclean is not called between parses, then the data
	used by the previous documents remains allocated, and pointers to
	it are valid.  Thus, the data for multiple documents can be accessible
	simultaneously, although only the current document can be manipulated
	with DOM.

	If you just want to access one document's data at a time (within a
	single context), then call xmlclean before each new parse.

    RETURNS
	(void)

    ARGUMENTS
        ctx (IN) XML context

    SEE ALSO
	xmlterm
*/
void xmlclean(xmlctx *ctx);

/*---------------------------------------------------------------------------
    NAME
        xmlparse [DOM X]

    FUNCTION
	Parses XML document from a URI

    DESCRIPTION
	Parses an XML given specified by a URI.  The parser must have been
	initialized successfully with a call to xmlinit or xmlinitenc first.

	Data pointers returned by DOM APIs remain valid until xmlclean
	or xmlterm is called.  For SAX, the data pointers only remain
	valid for the duration of the user's callback function.  That is,
	once the callback function has returned, the data pointers become
	invalid.  If longer access is needed, the data must be saved,
	either in the user's own store, or in the XML memory's pool using
	stringSave (or stringSave2 for UCS2 data).

	Parser options are specified as flag bits OR'd together into the
	"flags" mask.  Flags are:

        XML_FLAG_VALIDATE turns validation on.  By default, the parser does
	not validate the input.  To validate against a DTD, set this flag.
	Validation problems are considered warnings, not errors, and by
	default validation will continue after warnings have occurred.  To
	treat warnings as errors set the flag XML_FLAG_STOP_ON_WARNING.

        XML_FLAG_DISCARD_WHITESPACE causes extraneous whitespace to be
	discarded.  The default behavior for whitespace processing is to be
	fully conformant to the XML 1.0 spec, i.e. all whitespace is reported
	back to the application, but it is indicated which whitespace is
	"ignorable".  However, some applications may prefer to set the
	XML_FLAG_DISCARD_WHITESPACE which will discard all whitespace
	between an end-element tag and the following start-element tag.

	XML_FLAG_STOP_ON_WARNING stops validation on warnings.  Validation
	problems are considered warnings (non-fatal) unless this flag is set.
	If set, validation will stop after the first warning.

	XML_FLAG_DTD_ONLY parse an external subset.  This is the same as
	calling xmlparsedtd; it parses an external subset (DTD) instead of
	a complete XML document.  Used primarily by the Class Generator so
	that it may generate classes from a DTD without need of a complete
	document.

	XML_FLAG_WARN_DUPLICATE_ENTITY causes a warning to be emitted if a
	duplicate entity declaration is found.  A duplicate entity declaration
	is usually silently ignored.  When set, this flag causes a warning to
	be emitted instead.

	XML_FLAG_FORCE_INCODING forced input documents to be interpreted
	in the encoding "incoding".  The default input encoding may be
	specified as incoding, which overrides the incoding given to xmlinit.
	If the input's encoding cannot be determined automatically (based on
	BOM, XMLDecl, etc) then it is assumed to be incoding.  IANA/Mime
	encoding names should be used, "UTF-8", "ASCII", etc.  If
	XML_FLAG_FORCE_INCODING is set, the document will be interpreted as
	"incoding" regardless.

	XML_FLAG_DONT_EXPAND_CHAR_REF when set causes character references
	to be left verbatim and not expanded.  For example, "&20;" normally
        turns into the space character, but when this flag is set, it would
	remain the four characters '&' '2' '0' and ';'.

    RETURNS
        (uword) numeric error code, XMLERR_OK [0] on success

    ARGUMENTS
        ctx      (I/O) XML context
	uri      (IN)  input URI
        incoding (IN)  default input encoding
        flags    (IN)  parse options [mask of flag bits]

    SEE ALSO
	xmlparsebuf, xmlparsefile, xmlparsestream, xmlparsedtd, xmlflags
*/
uword xmlparse(xmlctx *ctx, const oratext *uri,
               const oratext *incoding, xmlflags flags);

/*---------------------------------------------------------------------------
    NAME
        xmlparsebuf [DOM X]

    FUNCTION
	Parses XML document from a memory buffer

    DESCRIPTION
	Parses an XML given a buffer and its length.  The parser must have
	been initialized successfully with a call to xmlinit or xmlinitenc
	first.  See the notes for xmlparse for full documentation.

    RETURNS
        (uword) numeric error code, XMLERR_OK [0] on success

    ARGUMENTS
        ctx      (I/O) XML context
	buffer   (IN)  input buffer
	len      (IN)  length of buffer in bytes
        incoding (IN)  default input encoding
        flags    (IN)  parse options [mask of flag bits]

    SEE ALSO
	xmlparse, xmlparsefile, xmlparsestream, xmlparsedtd, xmlflags
*/
uword xmlparsebuf(xmlctx *ctx, const oratext *buffer, size_t len, 
                  const oratext *incoding, xmlflags flags);

/*---------------------------------------------------------------------------
    NAME
        xmlparsefile [DOM X]

    FUNCTION
	Parses XML document from a disk file

    DESCRIPTION
	Parses an XML given the path to a disk file.  The parser must have
	been initialized successfully with a call to xmlinit or xmlinitenc
	first.  See the notes for xmlparse for full documentation.

    RETURNS
        (uword) numeric error code, XMLERR_OK [0] on success

    ARGUMENTS
        ctx      (I/O)    XML context
	path     (IN)     disk file path
        incoding (IN)     default input encoding
        flags    (IN)     parse options [mask of flag bits]

    SEE ALSO
	xmlparse, xmlparsebuf, xmlparsestream, xmlparsedtd, xmlflags
*/
uword xmlparsefile(xmlctx *ctx, const oratext *path, 
                   const oratext *incoding, xmlflags flags);

/*---------------------------------------------------------------------------
    NAME
        xmlparsestream [DOM X]

    FUNCTION
	Parses XML document from a user-defined stream

    DESCRIPTION
	Parses an XML given the path from a user-defined stream.  The parser
	must have been initialized successfully with a call to xmlinit or
	xmlinitenc first.  See the notes for xmlparse for full documentation.

    RETURNS
        (uword) numeric error code, XMLERR_OK [0] on success

    ARGUMENTS
        ctx      (I/O) XML context
	stream   (IN)  user-defined stream
        incoding (IN)  default input encoding
        flags    (IN)  parse options [mask of flag bits]

    SEE ALSO
	xmlparse, xmlparsebuf, xmlparsefile, xmlparsedtd, xmlflags
*/
uword xmlparsestream(xmlctx *ctx, const void *stream, 
                     const oratext *incoding, xmlflags flags);

/*---------------------------------------------------------------------------
    NAME
        xmlparseorastream [DOM X]

    FUNCTION
	Parses XML document from an orastream

    DESCRIPTION
	Parses an XML given the path from an orastream (see orastruc.h).
	The parser must have been initialized successfully with a call to
	xmlinit or xmlinitenc first.  See the notes for xmlparse for full
	documentation.

    RETURNS
        (uword) numeric error code, XMLERR_OK [0] on success

    ARGUMENTS
        ctx      (I/O) XML context
	istream  (IN)  input orastream
        incoding (IN)  default input encoding
        flags    (IN)  parse options [mask of flag bits]

    SEE ALSO
	xmlparse, xmlparsebuf, xmlparsefile, xmlparsedtd, xmlflags
*/
uword xmlparseorastream(xmlctx *ctx, orastream *istream, 
                        const oratext *incoding, xmlflags flags);

/*---------------------------------------------------------------------------
    NAME
        xmlparsedtd [DOM X]

    FUNCTION
	Parses an external subset (DTD) specified by a URI

    DESCRIPTION
	Parses an external subset (DTD) specified by a URI.  Using this API
	is the same as calling xmlparse with XML_FLAG_DTD_ONLY set.  The
	parser must have been initialized successfully with a call to xmlinit
	or xmlinitenc first.  See the notes for xmlparse for full documentation.

    RETURNS
        (uword) numeric error code, XMLERR_OK [0] on success

    ARGUMENTS
        ctx      (I/O) XML context
	uri      (IN)  input URI
	name     (IN)  name of DTD
        incoding (IN)  default input encoding
        flags    (IN)  parse options [mask of flag bits]

    SEE ALSO
	xmlparse, xmlparsebuf, xmlparsefile, xmlparsestream, xmlflags
*/
uword xmlparsedtd(xmlctx *ctx, const oratext *filename,
                  oratext *name, const oratext *incoding, xmlflags flags);

/*---------------------------------------------------------------------------
    NAME
        xmlaccess [DOM X]

    FUNCTION
        Sets I/O callbacks for URI access method

    DESCRIPTION
        Sets the I/O callback functions for the given URI access type.  All
	three functions must be provided, and should be declared using
	the function prototype macros XML_OPENF, XML_CLOSEF and XML_READF.

    RETURNS
        (uword) numeric error code, XMLERR_OK [0] on success

    ARGUMENTS
        ctx    (IN) XML context
        access (IN) the XMLACCESS_xxx code
        openf  (IN) pointer to open function
        closef (IN) pointer to close function
        readf  (IN) pointer to read function

    SEE ALSO
	xmlacctype, XML_OPENF, XML_CLOSEF, XML_READF
*/
uword xmlaccess(xmlctx *ctx, xmlacctype access, XML_OPENF((*openf)),
                XML_CLOSEF((*closef)), XML_READF((*readf)));

/*---------------------------------------------------------------------------
    NAME
        isStandalone [DOM X]

    FUNCTION
	Returns value of standalone flag

    DESCRIPTION
        Returns the value of the standalone flag as specified in the
	document's XMLDecl.

    RETURNS
        (boolean) value of standalone flag

    ARGUMENTS
        ctx (IN) XML context
*/
boolean isStandalone(xmlctx *ctx);

/*---------------------------------------------------------------------------
    NAME
        isSingleChar [DOM X]

    FUNCTION
	Returns single-byte data encoding flag

    DESCRIPTION
        Returns a flag specifying if the data encoding is single-byte
	(ASCII, ISO-8859, EBCDIC, etc).  If FALSE, the data encoding
	may be multibyte or Unicode.

    RETURNS
        (boolean) value of single-char flag

    ARGUMENTS
        ctx (IN) XML context

    SEE ALSO
	isUnicode, getEncoding
*/
boolean isSingleChar(xmlctx *ctx);

/*---------------------------------------------------------------------------
    NAME
        isUnicode [DOM X]

    FUNCTION
	Returns Unicode data flag

    DESCRIPTION
        Returns a flag specifying whether the data encoding is Unicode
	(UCS2).  If FALSE, the data may be either single-byte or multibyte.

    RETURNS
        (boolean) value of Unicode flag

    ARGUMENTS
        ctx (IN) XML context

    SEE ALSO
	isSingleChar, getEncoding
*/
boolean isUnicode(xmlctx *ctx);

/*---------------------------------------------------------------------------
    NAME
        getEncoding [DOM X]

    FUNCTION
	Returns name of data encoding.

    DESCRIPTION
        This function returns the IANA/Mime name of the data encoding, e.g.
	"UTF-8", "ASCII", etc.

    RETURNS
        (oratext *) name of encoding

    ARGUMENTS
        ctx (IN) XML context

    SEE ALSO
	isSingleChar, isUnicode
*/
oratext *getEncoding(xmlctx *ctx);

/*---------------------------------------------------------------------------
    NAME
	saveString [DOM X]

    FUNCTION
	Saves single/multibyte string in XML context memory

    DESCRIPTION
	Allocates memory and saves the NULL-terminated single- or multi-byte
	string in the XML string pool.  Strings saved this way cannot be freed
	individually since they are stored head-to-tail in a single pool, for
	maximum compactness.  The memory is reused only when the entire pool is
	freed, after an xmlclean or xmlterm call.  Use saveString2 for saving
	Unicode strings.

    RETURNS
	(oratext *) pointer to saved string

    ARGUMENTS
	ctx (IN) XML context
	str (IN) pointer to single- or multi-byte string

    SEE ALSO
	saveString2
*/
oratext *saveString(xmlctx *ctx, oratext *str);

/*---------------------------------------------------------------------------
    NAME
	saveString2 [DOM X]

    FUNCTION
	Saves Unicode string in XML context memory

    DESCRIPTION
	Allocates memory and saves the NULL-terminated Unicode string in the
	XML string pool.  Note that a Unicode string is terminated with TWO
	NULL bytes, not just one!  Strings saved this way cannot be freed
	individually since they are stored head-to-tail in a single pool, for
	maximum compactness.  The memory is reused only when the entire pool
	is freed, after an xmlclean or xmlterm call.  Use saveString for
	saving single- or multi-byte strings.

    RETURNS
	(oratext *) pointer to saved Unicode string

    ARGUMENTS
	ctx  (IN) XML context
	ustr (IN) pointer to Unicode string

    SEE ALSO
	saveString
*/
ub2 *saveString2(xmlctx *ctx, ub2 *ustr);

/*---------------------------------------------------------------------------
    NAME
	printStream [DOM X]

    FUNCTION
	Prints XML tree to stdio stream

    DESCRIPTION
	Pretty-prints (formats) an XML document rooted at the given node
	to a stdio stream.  The top level is indented step*level spaces,
	the next level step*(level+1) spaces, etc.  Output will be in the
	data encoding.

    RETURNS
	(void)

    ARGUMENTS
	stream (IN) output stdio stream [stdout, etc]
	node   (IN) root node to print
	step   (IN) spaces to indent each level [0-4]
	level  (IN) initial nesting level [0 for root]

    SEE ALSO
	printStreamEnc, printOraStream, printBuffer, printSize
*/
void printStream(FILE *stream, xmlnode *node, uword step, uword level);

/*---------------------------------------------------------------------------
    NAME
	printStreamEnc [DOM X]

    FUNCTION
	Prints XML tree to stdio stream in specified encoding

    DESCRIPTION
	Pretty-prints (formats) an XML document rooted at the given node
	to a stdio stream.  The entire document will be in the encoding
	specified (by name); if no encoding is given, the document is
	output in its current (data) encoding.  The top level is indented
	step*level spaces, the next level step*(level+1) spaces, etc.  Flags:

	XML_FLAG_PRINT_XMLDECL says to always print an XMLDecl before
	the root element.  If (node==DOC), an XMLDecl is always printed.

    RETURNS
	(size_t) total number of bytes written to stream

    ARGUMENTS
	stream   (IN) output stdio stream [stdout, etc]
	node     (IN) root node to print
	step     (IN) spaces to indent each level [0-4]
	level    (IN) initial nesting level [0 for root]
	encoding (IN) printed encoding [NULL for data current encoding]
        flags    (IN) mask of flag bits

    SEE ALSO
	printStreamEnc, printOraStream, printBuffer, printSize
*/
size_t printStreamEnc(FILE *stream, xmlnode *node, uword step, uword level,
                      oratext *encoding, xmlpflags flags);

/*---------------------------------------------------------------------------
    NAME
	printOraStream [DOM X]

    FUNCTION
	Prints XML tree to orastream in specified encoding

    DESCRIPTION
	Pretty-prints (formats) an XML document rooted at the given node
	to an orastream.  The entire document will be in the encoding
	specified (by name); if no encoding is given, the document is
	output in its current (data) encoding.  The top level is indented
	step*level spaces, the next level step*(level+1) spaces, etc.  Flags:

	XML_FLAG_PRINT_XMLDECL says to always print an XMLDecl before
	the root element.  If (node==DOC), an XMLDecl is always printed.

    RETURNS
	(size_t) total number of bytes written to stream

    ARGUMENTS
	ostream  (IN) output orastream
	node     (IN) root node to print
	step     (IN) spaces to indent each level [0-4]
	level    (IN) initial nesting level [0 for root]
	encoding (IN) printed encoding [NULL for data current encoding]
        flags    (IN) mask of flag bits

    SEE ALSO
	printStream, printStreamEnc, printBuffer, printSize
*/
size_t printOraStream(orastream *ostream, xmlnode *node, uword step,
		      uword level, oratext *encoding, xmlpflags flags);

/*---------------------------------------------------------------------------
    NAME
	printBuffer [DOM X]

    FUNCTION
	Prints XML tree to memory buffer

    DESCRIPTION
	Pretty-prints an XML document rooted at the given node to a buffer.
	The top level is indented step*level spaces, the next level
	step*(level+1) spaces, etc.  Output will be in the data encoding.

    RETURNS
	(void)

    ARGUMENTS
	buffer (IN) output buffer
	bufsiz (IN) size of buffer
	node   (IN) root node to print
	step   (IN) spaces to indent each level [0-4]
	level  (IN) initial nesting level [0 for root]

    SEE ALSO
	printBufferEnc, printCallbackEnc, printStream,
	printStreamEnc, printOraStream, printSize
*/
void printBuffer(oratext *buffer, size_t bufsiz, xmlnode *node,
                 uword step, uword level);

/*---------------------------------------------------------------------------
    NAME
	printBufferEnc [DOM X]

    FUNCTION
	Prints XML tree to memory buffer in specified encoding

    DESCRIPTION
	Pretty-prints an XML document rooted at the given node to a buffer.
	The entire document will be in the encoding specified (by name); if
	no encoding is given, the document is output in its current (data)
	encoding.  The top level is indented step*level spaces, the next level
	step*(level+1) spaces, etc.  Output will be in the data encoding.
	Flags:

	XML_FLAG_PRINT_XMLDECL says to always print an XMLDecl before
	the root element.  If (node==DOC), an XMLDecl is always printed.

    RETURNS
	(size_t) total number of bytes written to stream

    ARGUMENTS
	buffer   (IN) output buffer
	bufsiz   (IN) size of buffer
	node     (IN) root node to print
	step     (IN) spaces to indent each level [0-4]
	level    (IN) initial nesting level [0 for root]
	encoding (IN) printed encoding [NULL for data current encoding]
        flags    (IN) mask of flag bits

    SEE ALSO
	printBuffer, printCallbackEnc, printStream,
	printStream, printStreamEnc, printOraStream, printSize
*/
size_t printBufferEnc(oratext *buffer, size_t bufsiz, xmlnode *node,
                      uword step, uword level, oratext *encoding,
                      xmlpflags flags);

/*---------------------------------------------------------------------------
    NAME
	printSize [DOM X]

    FUNCTION
	Returns size of formatted XML tree

    DESCRIPTION
	Returns the length of XML printed representation, without actually
	outputting anything.  Can be used to calculate the size of the buffer
	needed for allocation.  Caution, about as expensive as formatting it
	in the first place!  The top level is indented step*level spaces,
	the next level step*(level+1) spaces, etc.  Formatting is in the
	data encoding, however size is returned in BYTES, not characters.

    RETURNS
	(size_t) formatted length in bytes

    ARGUMENTS
	node   (IN) root node
	step   (IN) spaces to indent each level [0-4]
	level  (IN) initial nesting level [0 for root]

    SEE ALSO
	printSizeEnc, printStream, printBuffer
*/
size_t printSize(xmlnode *node, uword step, uword level);

/*---------------------------------------------------------------------------
    NAME
	printSizeEnc [DOM X]

    FUNCTION
	Returns size of formatted XML tree in specified encoding

    DESCRIPTION
	Returns the length of the XML printed representation of a
	subtree (in the specified encoding), without actually printing
	anything.  If no encoding is given, the current (data) encoding
	is used.  Caution, about as expensive as formatting it in the
	first place!  The top level is indented step*level spaces,
	the next level step*(level+1) spaces, etc.  Formatting is in the
	data encoding, however size is returned in BYTES, not characters.

	XML_FLAG_PRINT_XMLDECL says to always print an XMLDecl before
	the root element.  If (node==DOC), an XMLDecl is always printed.

    RETURNS
	(size_t) size of formatted subtree in bytes

    ARGUMENTS
	node     (IN) root node
	step     (IN) spaces to indent each level [0-4]
	level    (IN) initial nesting level [0 for root]
	encoding (IN) printed encoding [NULL for data current encoding]
        flags    (IN) mask of flag bits

    SEE ALSO
	printSize, printStream, printBuffer
*/
size_t printSizeEnc(xmlnode *node, uword step, uword level,
                    oratext *encoding, xmlpflags flags);

/*---------------------------------------------------------------------------
    NAME
	freeElements [DOM X]

    FUNCTION
	Frees an allocated list of element nodes

    DESCRIPTION
	Frees an allocated list of element nodes.  Used primarily to free the
	lists created by getElementsByTagName.

    RETURNS
	(void)

    ARGUMENTS
	ctx  (IN) XML context
	list (IN) list of nodes to free

    SEE ALSO
	getElementsByTagName
*/
void freeElements(xmlctx *ctx, xmlnodes *list);

/*---------------------------------------------------------------------------
    NAME
	setDocOrder [DOM X]

    FUNCTION
	Sets the document order for each node in a Document

    DESCRIPTION
	Sets the document order for each node in the current document.  Must
	be called once on the final document before XSLT processing can occur.
	Note this is called automatically by the XSLT processor, so ordinarily
	the user need not make this call.

    RETURNS
	(ub4) last ID# assigned

    ARGUMENTS
	ctx      (IN) XML context
	start_id (IN) initial ID# to assign

    SEE ALSO
	getDocOrder
*/
ub4 setDocOrder(xmlctx *ctx, ub4 start_id);

/*---------------------------------------------------------------------------
    NAME
	xmlWhere [DOM X]

    FUNCTION
	Returns the location where an error occured

    DESCRIPTION
	Returns the location (line#, path) where an error occurred.  The
	error location is a stack: to fetch all items, set index=0 and
	call repeatedly, incrementing index until FALSE is returned.
	This function must be called from the user's own error callback
	function, while the error stack is current.  It will NOT return
	valid information after the top-level parse functions have
	returned, only during the commission of an error!

    RETURNS
	(boolean) idx is valid, an error occurred

    ARGUMENTS
	ctx  (IN)  XML context
	line (OUT) line# where err occurred
	path (OUT) path/URL where err occurred
	idx  (IN)  location in error stack (starting at 0)

    SEE ALSO
	xmlLocation
*/
boolean xmlwhere(xmlctx *ctx, ub4 *line, oratext **path, uword idx);
#define xmlWhere xmlwhere

/*---------------------------------------------------------------------------
    NAME
	xmlLocation [DOM X]

    FUNCTION
	Returns the current location while parsing

    DESCRIPTION
	Returns the current location (line#, path) while parsing.  If
	called before or after parsing, 0 and NULL will be returned
	respectively.  The path will be either the URL or filespec;
	for other parsing methods (from stream or buffer), NULL is
	returned.

    RETURNS
	(void)

    ARGUMENTS
	ctx  (IN)  XML context
	line (OUT) current line#
	path (OUT) current path/URL

    SEE ALSO
	xmlWhere
*/
void xmlLocation(xmlctx *ctx, ub4 *line, oratext **path);

/*---------------------------------------------------------------------------
    NAME
	associateDomDocument [DOM X]

    FUNCTION
	Mechanism to associate xdkdomdoc with xmlctx

    DESCRIPTION
	Associates an xdkdomdoc to a given xmlctx.  This association allows
	usage of the XSLT, XPath, and XML Schema Validator APIs with an
	xdkdomdoc.   The XDB DOM (OCIDomDocument) object is one particular
	type of xdkdomdoc.  xdkdomdoc is defined in xdkdomdoc.h.

    RETURNS
	(void)

    ARGUMENTS
	ctx  (IN) XML context
	doc  (IN)  xdkdomdoc to be associated
*/
void associateDomDocument(xmlctx *ctx, void *doc);

/*---------------------------------------------------------------------------
                           Package DOM - DOM APIs

    Since the DOM standard is object-oriented, for this C adaptation, some
    changes had to be made:

    Reused function names had to be expanded, e.g. getValue in the
    attribute class is given the unique name getAttrValue, matching
    the pattern established by getNodeValue.

    Also, some functions were added to extend the DOM.  For example,
    there is no function defined which returns the number of children
    of a node, so numChildNodes was invented, etc.

    The implementation of this DOM interface follows REC-DOM-Level-1-19981001.

  ---------------------------------------------------------------------------*/

/****************************************************************************
			       Interface Node
 ****************************************************************************/

/*---------------------------------------------------------------------------
    NAME
        getNodeName [DOM 1]

    FUNCTION
	Returns name of a node

    DESCRIPTION
        Returns the (fully-qualified) name of a node (in the data encoding),
	for example "bar" or "foo:bar".  These functions are synonyms and
	return the same thing.

	Note that some node types have fixed names: "#text", "#cdata-section",
	"#comment", "#document", "#document-fragment".

    RETURNS
        (oratext *) node's QName [in data encoding]

    ARGUMENTS
        node (IN) node whose QName to return

    SEE ALSO
	getNodeQualifiedName, getNodeNamespace, getNodePrefix, getNodeLocal
*/
const oratext *getNodeName(const xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
	getNodeQualifiedName [DOM 2 Node.nodeName attribute]

    FUNCTION
	Returns name of a node

    DESCRIPTION
        Returns the (fully-qualified) name of a node (in the data encoding),
	for example "bar" or "foo:bar".  These functions are synonyms and
	return the same thing.

	Note that some node types have fixed names: "#text", "#cdata-section",
	"#comment", "#document", "#document-fragment".

    RETURNS
        (oratext *) node's QName [in data encoding]

    ARGUMENTS
        node (IN) node whose QName to return

    SEE ALSO
	getNodeName, getNodeNamespace, getNodePrefix, getNodeLocal
*/
const oratext *getNodeQualifiedName(const xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
        getNodeNamespace [DOM 2 Node.namespaceURI attribute]

    FUNCTION
	Returns namespace URI of a node

    DESCRIPTION
        Returns the namespace URI for a node (in the data encoding).  If
	the node's name is not qualified (does not contain a namespace
	prefix), it will have the default namespace in effect when the
	node was created (which may be NULL).

    EXAMPLE
	<pfx:foo xmlns:pfx="example_namespace"/>
	getNodeNamespace(element pfx:foo) --> "example_namespace"

    RETURNS
        (oratext *) node's namespace URI [in data encoding] or NULL

    ARGUMENTS
        node (IN) node whose namespace URI to return

    SEE ALSO
	getNodeQualifiedName, getNodePrefix, getNodeLocal
*/
const oratext *getNodeNamespace(const xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
        getNodePrefix [DOM 2 Node.prefix attribute]

    FUNCTION
	Returns namespace prefix of a node

    DESCRIPTION
        Returns the namespace prefix for a node.  If the node's name is
	not fully qualified (has no prefix), NULL is returned.

    EXAMPLE
	<pfx:foo xmlns:pfx="example_namespace"/>
	getNodePrefix(element pfx:foo) --> "pfx"

    RETURNS
        (oratext *) node's namespace prefix [in data encoding] or NULL

    ARGUMENTS
        node (IN) node whose namespace prefix to return

    SEE ALSO
	getNodeQualifiedName, getNodeNamespace, getNodeLocal, prefixToURI
*/
const oratext *getNodePrefix(const xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
        getNodeLocal [DOM 2 Node.localName attribute]

    FUNCTION
	Returns namespace local name of a node

    DESCRIPTION
        Returns the namespace local name for a node.  If the node's name
	is not fully qualified (has no prefix), then the local name is
	the same as the name.

    EXAMPLE
	<pfx:foo xmlns:pfx="example_namespace"/>
	getNodeLocal(element pfx:foo) --> "foo"

    RETURNS
        (oratext *) node's namespace local name [in data encoding]

    ARGUMENTS
        node (IN) node whose namespace local name to return

    SEE ALSO
	getNodeQualifiedName, getNodeNamespace, getNodeLocal
*/
const oratext *getNodeLocal(const xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
        getNodeValue [DOM 1]

    FUNCTION
	Returns value (character data) of a node

    DESCRIPTION
        Returns the "value" (associated character data) for a node.
	Character and general entities will have been replaced.  Only
	Attr, CDATA, Comment, PI and Text nodes have values, all other
	node types have NULL value.

    EXAMPLE
	"<foo>data</foo>"
	getNodeValue(node foo) --> NULL
	getNodeValue(foo's first child) --> "data"

    RETURNS
        (oratext *) node's value [in data encoding] or NULL

    ARGUMENTS
        node (IN) node whose value to return

    SEE ALSO
	setNodeValue, getAttrValue, setAttrValue
*/
const oratext* getNodeValue(const xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
        setNodeValue [DOM 1]

    FUNCTION
	Sets the new value (character data) of a node

    DESCRIPTION
        Sets a node's "value" (associated character data).  Does not allow
        setting the value to NULL.  Only Attr, CDATA, Comment, PI and Text
	nodes have values; trying to set the value of another type of node
	is a no-op.  Note that the new value must be in the data encoding!
	It is not verified, converted, or checked.  If bad data is set for
	a node, bad things may happen-- GIGO!

    RETURNS
        (void)

    ARGUMENTS
        node (IN) node whose value to set
        data (IN) new data for node [in data encoding]

    SEE ALSO
	getNodeValue, getAttrValue, setAttrValue
*/
void setNodeValue(xmlnode *node, const oratext *data);

/*---------------------------------------------------------------------------
    NAME
        getNodeType [DOM 1]

    FUNCTION
	Returns the type code of a node

    DESCRIPTION
        Returns the type code of a node.  The type names and numeric values
	match the DOM specification (and are #defined in oraxml.h):

	ELEMENT_NODE, ATTRIBUTE_NODE, TEXT_NODE, CDATA_SECTION_NODE,
	ENTITY_REFERENCE_NODE, ENTITY_NODE, PROCESSING_INSTRUCTION_NODE,
	COMMENT_NODE, DOCUMENT_NODE, DOCUMENT_TYPE_NODE,
	DOCUMENT_FRAGMENT_NODE, NOTATION_NODE

	Additional node types (not in the DOM standard) are as follows:

	ELEMENT_DECL_NODE, ATTR_DECL_NODE, CP_ELEMENT_NODE, CP_CHOICE_NODE,
	CP_SEQUENCE_NODE, CP_PCDATA_NODE, CP_STAR_NODE, CP_PLUS_NODE,
	CP_OPT_NODE

    RETURNS
        (xmlntype) node's type code

    ARGUMENTS
        node (IN) node whose type to return

    SEE ALSO
	xmlntype
*/
xmlntype getNodeType(const xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
        getParentNode [DOM 1]

    FUNCTION
	Returns a node's parent

    DESCRIPTION
        Returns a node's parent node.  All nodes types except Attr, Document,
	DocumentFragment, Entity, and Notation may have a parent (these five
	exceptions have a NULL parent).  If a node has just been created and
	has not yet added to the tree, or if it has been removed from the tree,
	its parent is also NULL.

    RETURNS
        (xmlnode *) node's parent node

    ARGUMENTS
        node (IN) node whose parent to return
*/
xmlnode *getParentNode(const xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
        getChildNodes [DOM 1]

    FUNCTION
	Returns a node's children

    DESCRIPTION
        Returns a list of the node's children, or NULL if it has no
	children.  Only Element, Document, DTD, and DocumentFragment
	nodes may have children; all other types will return NULL.

	Note that an empty list may be returned if the node once had
	children, but all have been removed!  So, presense of the list
	alone does not mean the node has children.  You must check the
	size of the list with numChildNodes or use hasChildNodes first.

	The xmlnodes structure is opaque and can only be manipulated
	with functions in the NamedNodeMap interface.

    RETURNS
        (xmlnodes *) list of node's children or NULL

    ARGUMENTS
        node  (IN) node whose children to return

    SEE ALSO
	hasChildNodes, numChildNodes, getNamedItem, setNamedItem,
	removeNamedItem, getChildNode, getNodeMapLength
*/
xmlnodes* getChildNodes(const xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
        getFirstChild [DOM 1]

    FUNCTION
	Returns the first child of a node

    DESCRIPTION
        Returns the first child of a node, or NULL if the node has no
	children.  Only Element, Document, DTD, and DocumentFragment
        nodes may have children; all other types will return NULL.

    RETURNS
        (xmlnode *) node's first child

    ARGUMENTS
        node (IN) node whose first child to return

    SEE ALSO
	getChildNodes, getLastChild
*/
xmlnode *getFirstChild(const xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
        getLastChild [DOM 1]

    FUNCTION
	Returns the last child of a node

    DESCRIPTION
        Returns the last child of a node, or NULL if the node has no
	children.  Only Element, Document, DTD, and DocumentFragment
	nodes may have children; all other types will return NULL.

    RETURNS
        (xmlnode *) node's last child

    ARGUMENTS
        node  (IN) node whose last child to return

    SEE ALSO
	getChildNodes, getFirstChild
*/
xmlnode *getLastChild(const xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
        getPreviousSibling [DOM 1]

    FUNCTION
	Returns the previous sibling of a node

    DESCRIPTION
        Returns the node preceding a node at the same level in the DOM tree.
	That is, for each child of a parent node, the previous sibling of
	that child is the child which came before it.  If a node is the first
	child of its parent, or has no parent, NULL is returned.

    RETURNS
        (xmlnode *) node's previous sibling

    ARGUMENTS
        node (IN) node whose previous sibling to return

    SEE ALSO
	getNextSibling
*/
xmlnode *getPreviousSibling(const xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
        getNextSibling [DOM 1]

    FUNCTION
	Returns the next sibling of a node

    DESCRIPTION
        Returns the node following a node at the same level in the DOM tree.
	That is, for each child of a parent node, the next sibling of that
	child is the child which comes after it.  If a node is the last child
	of its parent, or has no parent, NULL is returned.

    RETURNS
        (xmlnode *) node's next sibling

    ARGUMENTS
        node (IN) node whose next sibling to return

    SEE ALSO
	getPreviousSibling
*/
xmlnode *getNextSibling(const xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
        getAttributes [DOM 1]

    FUNCTION
	Returns the attributes of an element

    DESCRIPTION
        Returns a NamedNodeMap of attributes of an element node, or NULL if
	it has no attributes.  For other node types, NULL is returned.  Note
	that if an element once had attributes, but they have all been removed,
	an empty list will be returned.  So, presense of the list does not mean
	the element has attributes.  You must check the size of the list with
	numAttributes or use hasChildNodes first.

    RETURNS
        (xmlnodes *) element node's attributes

    ARGUMENTS
        node  (IN) element node whose attributes to return
*/
xmlnodes *getAttributes(const xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
        getOwnerDocument [DOM 1]

    FUNCTION
	Returns the document containing a node

    DESCRIPTION
        Returns the Document node associated with a node.  Each node belongs
	to a single xmlctx, and each xmlctx contains only one top-level
	Document node.  That Document node is returned, even if the given
	node has not yet been added to the DOM tree.  If no Document has been
	created yet, NULL is returned.

    RETURNS
        (xmlnode *) Document associated with the node

    ARGUMENTS
        node (IN) node whose associated Document to return

    SEE ALSO
	createDocument, createDocumentNS
*/
xmlnode *getOwnerDocument(xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
        insertBefore [DOM 1]

    FUNCTION
	Inserts a new child into a parent

    DESCRIPTION
        Inserts the node newChild before the existing child node refChild
	in the parent node.  If refChild is NULL, appends to parent's
	children as per appendChild; otherwise it must be a child of the
	given parent.  If newChild is a DocumentFragment, all of its children
	are inserted (in the same order) before refChild; the DocumentFragment
	node itself is not.  If newChild is already in the DOM tree, it is
	first removed from its current position.

    RETURNS
        (xmlnode *) the new node inserted

    ARGUMENTS
        ctx      (IN) XML context
        parent   (IN) parent node
        newChild (IN) new node to insert
        refChild (IN) reference node, or NULL to append

    SEE ALSO
	appendChild, replaceChild, removeChild
*/
xmlnode *insertBefore(xmlctx *ctx, xmlnode *parent,
                      xmlnode *newChild, xmlnode *refChild);

/*---------------------------------------------------------------------------
    NAME
        replaceChild [DOM 1]

    FUNCTION
	Replaces one child node with another

    DESCRIPTION
        Replaces the child node oldChild with the new node newChild in
	oldChild's parent, and returns oldChild (which is now orphaned,
	with a NULL parent).  If newChild is a DocumentFragment, all of
	its children are inserted in place of oldChild; the DocumentFragment
	node itself is not.  If newChild is already in the DOM tree, it is
	first removed from its current position.

    RETURNS
        (xmlnode *) oldChild, the node replaced

    ARGUMENTS
        ctx      (IN) XML context
        newChild (IN) new node to replace with
        oldChild (IN) old node being replaced

    SEE ALSO
	insertBefore, appendChild, removeChild
*/
xmlnode *replaceChild(xmlctx *ctx, xmlnode *newChild, xmlnode *oldChild);

/*---------------------------------------------------------------------------
    NAME
        removeChild [DOM 1]

    FUNCTION
	Removes a child node

    DESCRIPTION
        Removes a node from its parent's list of children and returns it. 
	The node is orphaned; its parent will be NULL after removal.

    RETURNS
        (xmlnode *) the node removed

    ARGUMENTS
        node (IN) node being removed

    SEE ALSO
	appendChild, insertBefore, replaceChild
*/
xmlnode *removeChild(xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
        appendChild [DOM 1]

    FUNCTION
	Appends a new child to a parent

    DESCRIPTION
        Appends the node to the end of the parent's list of children and
	returns the new node.  If newChild is a DocumentFragment, all of
	its children are appended in original order; the DocumentFragment
	node itself is not.

    RETURNS
        (xmlnode *) the node appended

    ARGUMENTS
        ctx      (IN) XML context
        parent   (IN) parent node
        newChild (IN) new node to append

    SEE ALSO
	insertBefore, replaceChild, removeChild
*/
xmlnode *appendChild(xmlctx *ctx, xmlnode *parent, xmlnode *newChild);

/*---------------------------------------------------------------------------
    NAME
        hasChildNodes [DOM 1]

    FUNCTION
	Determines if a node has children

    DESCRIPTION
        Test if a node has children.  Only Element, Document, DTD, and
	DocumentFragment nodes may have children.  Note that just because
	getChildNodes returns a list does not mean the node actually has
	children, since the list may be empty.

    RETURNS
        (boolean) TRUE if there are children, FALSE if not

    ARGUMENTS
        node (IN) node to test

    SEE ALSO
	getChildNodes, numChildNodes
*/
boolean hasChildNodes(const xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
        numChildNodes [DOM X]

    FUNCTION
	Returns the number of children of a node

    DESCRIPTION
        Returns the number of children in a xmlnodes list (as returned by
	getChildNodes).  Only Element, Document, DTD, and DocumentFragment
	nodes may have children, all other types return 0.  Note that just
	because getChildNodes returns a list does not mean that it contains
	any children; it may be an empty list with zero length.

    RETURNS
        (size_t) number of children

    ARGUMENTS
        nodes (IN) list of nodes from getChildNodes

    SEE ALSO
	getChildNodes, hasChildNodes
*/
size_t numChildNodes(const xmlnodes *nodes);

/*---------------------------------------------------------------------------
    NAME
        hasAttributes [DOM X]

    FUNCTION
	Determines if an element has attributes

    DESCRIPTION
        Tests whether an element node has any defined attributes.  Only
	an element node may have attributes; all other types will return
	FALSE.

    RETURNS
        (boolean) TRUE if element has attributes, FALSE if not

    ARGUMENTS
        node (IN) element node to check for attributes

    SEE ALSO
	getAttributes, numAttributes, getAttribute, getAttributeIndex
*/
boolean hasAttributes(const xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
        numAttributes [DOM X]

    FUNCTION
	Returns the number of attributes of an element

    DESCRIPTION
        Returns the number of attributes in an xmlnodes list.  Note that
	just because a list is returned by getAttributes does not necessarily
	mean it contains any attributes; it may be an empty list with zero
	length.

    RETURNS
        (size_t) number of attributes in list

    ARGUMENTS
        attrs (IN) list of attributes from getAttributes

    SEE ALSO
	getAttributes, hasAttributes, getAttribute, getAttributeIndex
*/
size_t numAttributes(const xmlnodes *attrs);

/*---------------------------------------------------------------------------
    NAME
        cloneNode [DOM 1]

    FUNCTION
	Creates a duplicate of a node

    DESCRIPTION
	Creates and returns a duplicate of a node.  The duplicate node has
	no parent.  Cloning an Element copies all attributes and their values,
	including those generated by the XML processor to represent defaulted
	attributes, but it does not copy any text it contains unless it is a
	deep clone, since the text is contained in a child Text node.  Cloning
	any other type of node simply returns a copy of the node.  Note that a
	clone of an unspecified Attr node is specified.  If deep is TRUE, all
	children of the node are recursively cloned, and the cloned node will
	have cloned children; a non-deep clone will have no children.

    RETURNS
        (xmlnode *) new, cloned node

    ARGUMENTS
	ctx  (IN) XML context
	old  (IN) node to clone
	deep (IN) recursively clone children?

    SEE ALSO
	importNode
*/
xmlnode *cloneNode(xmlctx *ctx, const xmlnode *old, boolean deep);

/*---------------------------------------------------------------------------
    NAME
        getDocOrder [DOM X]

    FUNCTION
	Returns the document order of a node

    DESCRIPTION
        Returns the document order cardinal for a node.  setDocOrder must
        have been called first or all nodes will have a 0 order!  Used
	primarily by the XSLT processor, which requires document order for
	node comparisons.  Nodes are numbered by the order in which they
	would be encountered in a preorder traversal of the tree.  The
	root node's order is specified to setDocOrder, but regardless of
	the absolute numbering, a node which comes first in the document
	will have a lower order than a node which comes later.

    RETURNS
        (ub4) document order cardinal for node

    ARGUMENTS
        node (IN) node whose doc order to return

    SEE ALSO
	setDocOrder
*/
ub4 getDocOrder(xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
        prefixToURI [DOM X]

    FUNCTION
	Maps a namespace prefix to a URI

    DESCRIPTION
        Given a namespace prefix and a node, returns the namespace URI
	mapped to that prefix.  If the given node doesn't have a matching
	prefix, its parent is tried, then its parent, and so on, all the
	way to the root node.  If the prefix is undefined, NULL is returned.

    RETURNS
        (oratext *) namespace URI for prefix

    ARGUMENTS
        node   (IN) node whose prefix to return
        prefix (IN) prefix to match

    SEE ALSO
	getNodePrefix, getNodeNamespace, getAttrPrefix, getAttrNamespace
*/
oratext *prefixToURI(xmlnode *node, oratext *prefix);

/*---------------------------------------------------------------------------
    NAME
        freeNode [DOM X]

    FUNCTION
	Frees memory allocated by a node

    DESCRIPTION
        Frees a node.  That is, frees all the space allocated by a single
	node.  Does NOT recurse to children.  The node should already have
	been removed from the document.

    RETURNS
        (void)

    ARGUMENTS
        node (IN) node to be freed
*/
void freeNode(xmlnode *node);

/****************************************************************************
			    Interface Attr
 ****************************************************************************/

/*---------------------------------------------------------------------------
    NAME
        getAttrName [DOM 1 Attr.getName]

    FUNCTION
	Returns an attribute's name

    DESCRIPTION
        Returns the fully-qualified name of an attribute (in the data
	encoding), for example "bar" or "foo:bar".  These functions are
	synonyms and return the same thing.

    RETURNS
        (oratext *) attribute's QName [in data encoding]

    ARGUMENTS
        attr (IN) attribute node whose name to return

    SEE ALSO
	getAttrQualifiedName, getAttrNamespace, getAttrPrefix, getAttrLocal
*/
const oratext *getAttrName(const xmlnode *attr);

/*---------------------------------------------------------------------------
    NAME
	getAttrQualifiedName [DOM X]

    FUNCTION
	Returns an attribute's name

    DESCRIPTION
        Returns the fully-qualified name of an attribute (in the data
	encoding), for example "bar" or "foo:bar".  These functions are
	synonyms and return the same thing.

    RETURNS
        (oratext *) attribute's QName [in data encoding]

    ARGUMENTS
        attr (IN) attribute node whose name to return

    SEE ALSO
	getAttrName, getAttrNamespace, getAttrPrefix, getAttrLocal
*/
const oratext *getAttrQualifiedName(const xmlnode *attr);

/*---------------------------------------------------------------------------
    NAME
        getAttrNamespace [DOM X]

    FUNCTION
	Returns an attribute's namespace URI

    DESCRIPTION
        Returns an attribute's namespace URI (in the data encoding).  If
	the attribute's name is not qualified (does not contain a namespace
	prefix), it will have the default namespace in effect when the node
	was created (which may be NULL).

    EXAMPLE
	<foo xmlns:pfx="example_namespace" pfx:bar="bar_value"/>
	getAttrNamespace(attr pfx:bar) --> "example_namespace"

    RETURNS
        (oratext *) attribute's namespace URI [in data encoding] or NULL

    ARGUMENTS
        attr (IN) attribute whose namespace URI to return

    SEE ALSO
	getAttrQualifiedName, getAttrPrefix, getAttrLocal
*/
const oratext *getAttrNamespace(const xmlnode *attr);

/*---------------------------------------------------------------------------
    NAME
        getAttrPrefix [DOM X]

    FUNCTION
	Returns an attribute's namespace prefix

    DESCRIPTION
        Returns an attribute's namespace prefix (in the data encoding).  If
	the attribute's name is not fully qualified (has no prefix), NULL
	is returned.

    EXAMPLE
	<foo xmlns:pfx="example_namespace" pfx:bar="bar_value"/>
	getAttrPrefix(attr pfx:bar) --> "pfx"

    RETURNS
        (oratext *) attribute's namespace prefix [in data encoding] or NULL

    ARGUMENTS
        attr (IN) attribute whose namespace prefix to return

    SEE ALSO
	getAttrQualifiedName, getAttrNamespace, getAttrLocal
*/
const oratext *getAttrPrefix(const xmlnode *attr);

/*---------------------------------------------------------------------------
    NAME
        getAttrLocal [DOM X]

    FUNCTION
	Returns an attribute's namespace local name

    DESCRIPTION
        Returns an attribute's namespace local name (in the data encoding).
        If the attribute's name is not fully qualified (has no prefix), then
	the local name is the same as the name.

    EXAMPLE
	<foo xmlns:pfx="example_namespace" pfx:bar="bar_value"/>
	getAttrLocal(attr pfx:bar) --> "bar"

    RETURNS
        (oratext *) string of local name [in data encoding]

    ARGUMENTS
        attr (IN) attribute whose local name to return
*/
const oratext *getAttrLocal(const xmlnode *attr);

/*---------------------------------------------------------------------------
    NAME
        getAttrSpecified [DOM 1 Attr.getSpecified]

    FUNCTION
	Returns an attribute's specified flag

    DESCRIPTION
        Return the 'specified' flag for an attribute.  If the attribute was
	explicitly given a value in the original document, this is TRUE;
	otherwise, it is FALSE.  If the node is not an attribute, returns
	FALSE.  If the user sets an attribute's value through DOM, its
	specified flag will be TRUE.  To return an attribute to its default
	value (if it has one), the attribute should be deleted-- it will
	then be re-created automatically with the default value (and specified
	will be FALSE).

    RETURNS
        (boolean) value of attribute's specified flag

    ARGUMENTS
        attr (IN) attribute node whose specified flag to return

    SEE ALSO
	setAttrValue
*/
boolean getAttrSpecified(const xmlnode *attr);

/*---------------------------------------------------------------------------
    NAME
	setAttrValue [DOM 1 Attr.value attribute]

    FUNCTION
	Sets an attribute's value

    DESCRIPTION
	Sets the given attribute's value to data.  If the node is not an
	attribute, does nothing.  Note that the new value must be in the
	data encoding!  It is not verified, converted, or checked.  If bad
	data is set for the attribute, bad things may happen-- GIGO!  The
	attribute's specified flag will be TRUE after setting a new value.

    RETURNS
	(void)

    ARGUMENTS
	attr (IN) pointer to attribute node
	data (IN) new value for attribute [in data encoding]

    SEE ALSO
	getAttrSpecified, getAttrValue
*/
void setAttrValue(xmlnode *attr, const oratext *data);

/*---------------------------------------------------------------------------
    NAME
        getAttrValue [DOM 1 Attr.value attribute]

    FUNCTION
	Returns an attribute's value

    DESCRIPTION
        Returns the "value" (character data) of an attribute (in the data
	encoding).  Character and general entities will have been replaced.

    RETURNS
        (oratext *) value of attribute [in data encoding]

    ARGUMENTS
        attr (IN) attribute whose value to return

    SEE ALSO
	setAttrValue
*/
const oratext *getAttrValue(const xmlnode *attr);

/****************************************************************************
			    Interface Element
 ****************************************************************************/

/*---------------------------------------------------------------------------
    NAME
	nodeValid [DOM X]

    FUNCTION
	Determines if a node is valid again a DTD

    DESCRIPTION
	Validates an element node (and its children) against the current DTD.
	If the node is not an Element, returns XMLERR_NODE_TYPE and does
	nothing.  Only works on a DOM tree created by parsing with validation
	enabled; without initial validation, just returns success (no-op).

    RETURNS
	(uword) error code, XMLERR_OK [0] on success

    ARGUMENTS
	ctx  (IN) XML context
	node (IN) root node to validate

    SEE ALSO
	xmlparse
*/
uword nodeValid(xmlctx *ctx, xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
	getTagName [DOM 1]

    FUNCTION
	Returns the tagName of a node

    DESCRIPTION
	Returns the "tagName" of a node, which is the same as its name for
	now.  The DOM says "...even though there is a generic nodeName
	attribute on the Node interface, there is still a tagName attribute
	on the Element interface; these two attributes must contain the same
	value, but the Working Group considers it worthwhile to support both,
	given the different constituencies the DOM API must satisfy."

    RETURNS
	(oratext *) node's tagname [in data encoding]

    ARGUMENTS
	node (IN) node whose tagname to return

    SEE ALSO
	getNodeName
*/
const oratext *getTagName(const xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
        getAttribute [DOM 1]

    FUNCTION
	Returns an attribute's value given its name

    DESCRIPTION
        Returns the value of an element's attribute (specified by name).
	Note that an attribute may have the empty string as its value,
	but cannot be NULL.  If the element does not have an attribute
	with the given name, NULL is returned.

    RETURNS
        (oratext *) attribute's value [in data encoding] or NULL

    ARGUMENTS
        node (IN) element whose attributes to check
        name (IN) name of attribute

    SEE ALSO
	getAttributes, getAttributeIndex, getAttributeNode
*/
const oratext *getAttribute(const xmlnode *node, const oratext *name);

/*---------------------------------------------------------------------------
    NAME
        getAttributeIndex [DOM X]

    FUNCTION
	Returns an attribute by index

    DESCRIPTION
        Given an xmlnodes list of attributes (from getAttributes), returns
	an attribute specified by index (position).  The first attribute is
	index 0, the second is index 1, etc.  If specified attribute does
	not exist (index is too large), returns NULL.

    RETURNS
        (xmlnode *) specified attribute or NULL

    ARGUMENTS
        attrs (IN) list of attributes from getAttributes
        index (IN) index of attribute to return (zero-based)

    SEE ALSO
	getAttributes, numAttributes, getAttribute
*/
xmlnode *getAttributeIndex(const xmlnodes *attrs, size_t index);

/*---------------------------------------------------------------------------
    NAME
	setAttribute [DOM 1]

    FUNCTION
	Creates an attribute for an element

    DESCRIPTION
	Creates a new attribute for an element with the given name and value
	(which should be in the data encoding).  If the named attribute already
	exists, its value is simply replaced.  The name and value are not
	verified, converted, or checked.  If bad data is set, bad things may
	happen-- GIGO!  The value is not parsed, so entity references will not
	be expanded.  The attribute's Specified flag will be set.

    RETURNS
	(xmlnode *) pointer to (new or old) attribute node, or NULL

    ARGUMENTS
	ctx   (IN) XML context
	elem  (IN) element node
	name  (IN) new attribute's name [in data encoding]
	value (IN) new attribute's value [in data encoding]

    SEE ALSO
	createAttribute, setAttrValue, removeAttribute
*/
xmlnode *setAttribute(xmlctx *ctx, xmlnode *elem,
                      const oratext *name, const oratext *value);

/*---------------------------------------------------------------------------
    NAME
	setAttributeNode [DOM 1]

    FUNCTION
	Adds an attribute node to an element

    DESCRIPTION
	Adds a new attribute to an element.  If an attribute with newNode's
	name already exists, it is replaced and the old attribute is returned
	through oldNode.  If the attribute has a new name, it is added to the
	element's list and oldNode is set to NULL.

    RETURNS
	(boolean) success

    ARGUMENTS
	ctx     (IN)  XML context
	elem    (IN)  element node
	newNode (IN)  new attribute node
	oldNode (OUT) replaced attribute or NULL

    SEE ALSO
	createAttribute, setAttrValue
*/
boolean setAttributeNode(xmlctx *ctx, xmlnode *elem,
                         xmlnode *newNode, xmlnode **oldNode);

/*---------------------------------------------------------------------------
    NAME
	removeAttribute [DOM 1]

    FUNCTION
	Removes an attribute from an element (by name)

    DESCRIPTION
	Removes an attribute (specified by name).  If the removed attribute
	has a default value it is immediately re-created with that default.
	Note that the attribute is removed from the element's list of
	attributes, but the Attr node itself is not destroyed.

    RETURNS
	(void)

    ARGUMENTS
	elem (IN) element node
	name (IN) name of attribute to remove [in data encoding]

    SEE ALSO
	removeAttributeNode
*/
void removeAttribute(xmlnode *elem, const oratext *name);

/*---------------------------------------------------------------------------
    NAME
	getAttributeNode [DOM 1]

    FUNCTION
	Returns the named attribute of an element

    DESCRIPTION
	Returns an element's attribute specified by name.  If the node is
	not an element or the named attribute does not exist, returns NULL.

    RETURNS
	(xmlnode *) named attribute or NULL

    ARGUMENTS
	elem (IN) element node
	name (IN) name of attribute to get [in data encoding]

    SEE ALSO
	getAttribute, getAttributeIndex
*/
xmlnode *getAttributeNode(const xmlnode *elem, const oratext *name);

/*---------------------------------------------------------------------------
    NAME
	removeAttributeNode [DOM 1]

    FUNCTION
	Removes an attribute from an element (by pointer)

    DESCRIPTION
	Removes an attribute from an element.  If the attribute has a
	default value, it is immediately re-created with that value
	(Specified set to FALSE).  Returns the removed attribute on
	success, else NULL.

    RETURNS
	(xmlnode *) pointer to old attribute, or NULL on error

    ARGUMENTS
	elem (IN) element node
	attr (IN) removed attribute node or NULL

    SEE ALSO
	removeAttribute
*/
xmlnode *removeAttributeNode(xmlnode *elem, xmlnode *attr);

/*---------------------------------------------------------------------------
    NAME
	normalize [DOM 1]

    FUNCTION
	Merges adjacent text nodes in an element

    DESCRIPTION
	"Normalizes" the subtree rooted at an element, i.e. merges adjacent
	Text nodes children of elements.  Note that adjacent Text nodes will
	never be created during a normal parse, only after manipulation of
	the document with DOM calls.

    EXAMPLE
	<a>"XXX" "YYY"<b>"111" "222"</b></a>
	normalize(node a) -->
	<a>"XXXYYY"<b>"111222"</b></a>

    RETURNS
	(void)

    ARGUMENTS
	ctx  (IN) XML context
	elem (IN) root of subtree to normalize
*/
void normalize(xmlctx *ctx, xmlnode *elem);

/****************************************************************************
			    Interface DOMImplementation
 ****************************************************************************/

/*---------------------------------------------------------------------------
    NAME
	createDocument [DOM X]

    FUNCTION
	Creates a new Document node (non-namespace)

    DESCRIPTION
	Creates the top-level Document node in an xmlctx.  Each context can
	only contain a single document, rooted in a Document node.  If the
	context already contains a document, it is returned.  Otherwise a
	new Document node is created and set in the context.  This is a
	non-namespace-aware function; the Document will have NULL namespace
	URI and prefix and have the name "#document".  If a DTD (as created
	by createDocumentType) is specified (not NULL), it is added as a
	child of the document.  The DTD must not already be a child of
	another document!

    RETURNS
	(xmlnode *) existing or created Document node

    ARGUMENTS
	ctx   (IN) XML context

    SEE ALSO
	createDocumentNS, createDocumentType
*/
xmlnode* createDocument(xmlctx *ctx);

/*---------------------------------------------------------------------------
    NAME
	createDocumentNS [DOM 2 createDocument]

    FUNCTION
	Creates a new Document node (namespace-aware)

    DESCRIPTION
	Creates the top-level Document node in an xmlctx.  Each context can
	only contain a single document, rooted in a Document node.  If the
	context already contains a document, it is returned.  Otherwise a
	new Document node is created and set in the context.  This is a
	namespace-aware function; the Document's namespace URI and QName
	should be specified (but may be NULL).  If no name is provided, the
	document will be named "#document".  If a DTD (as created by
	createDocumentType) is specified (not NULL), it is added as a child
	of the document.  The DTD must not already be a child of another
	document!

    RETURNS
	(xmlnode *) existing or created Document node

    ARGUMENTS
	ctx   (IN) XML context
	imp   (IN) DOMImplementation structure
	uri   (IN) document's namespace URI [in data encoding] or NULL
	qname (IN) document's qualified name [in data encoding] or NULL
	dtd   (IN) document type (DTD)

    SEE ALSO
	createDocument, createDocumentType
*/
xmlnode* createDocumentNS(xmldomimp *imp, oratext *uri,
                          oratext *qname, xmlnode *dtd);

/*---------------------------------------------------------------------------
    NAME
	createDocumentType [DOM 2]

    FUNCTION
	Creates a new DTD node

    DESCRIPTION
	Creates and returns a DOCUMENT_TYPE (DTD) node.  Currently there is
	no way to populate the DTD; this function is provided in anticipation
	of future DOM versions.  The DTD may be associated with a new Document
	by createDocument or createDocumentNS.

    RETURNS
	(xmlnode *) created DTD node

    ARGUMENTS
	imp   (IN) DOMImplementation structure
	qname (IN) DTD's qualified name [in data encoding]
	pubid (IN) DTD's public identifier [in data encoding]
	sysid (IN) DTD's system identifier [in data encoding]

    SEE ALSO
	createDocument, createDocumentNS
*/
xmlnode* createDocumentType(xmldomimp *imp, oratext *qname,
                            oratext *pubid, oratext *sysid);

/*---------------------------------------------------------------------------
    NAME
        hasFeature [DOM 1]

    FUNCTION
	Tests if the DOM implementation supports a feature

    DESCRIPTION
        Tests if the DOM implementation supports a named feature with a
	certain version.  Note that version can only be "1.0" or "2.0"
	at present.  If omitted, supporting any version of the feature
	returns TRUE.

    DOM 1.0 FEATURES
	"XML"		 XML module
	"HTML"		 HTML module

    DOM 2.0 FEATURES
	"Core"		 Core module
	"XML"		 XML module
	"HTML"		 HTML module
	"Views"		 Views module
	"StyleSheets"	 Style Sheets module
	"CSS"		 CSS module
	"CSS2"		 CSS2 module
	"Events"	 Events module
	"UIEvents"	 User interface Events module
	"MouseEvents"	 Mouse Events module
	"MutationEvents" Mutation Events module
	"HTMLEvents"	 HTML Events module
	"Range"		 Range module
	"Traversal"	 Traversal module

    RETURNS
        (boolean) Feature is implemented in the specified version

    ARGUMENTS
        imp     (IN) XML DOMImplementation structure
        feature (IN) case-insensitive name of the feature [in data encoding]
        version (IN) version of feature [in data encoding]
*/
boolean hasFeature(xmldomimp *imp, const oratext *feature, 
                   const oratext *version);

/****************************************************************************
			    Interface Document
 ****************************************************************************/

/*---------------------------------------------------------------------------
    NAME
        getDocType [DOM 1 Document.DocumentType attribute]

    FUNCTION
	Returns the current document's DTD

    DESCRIPTION
        Returns the DTD node associated with current document.  The DTD
	cannot be edited, but its children may be retrieved with getChildNodes
	as for other node types.

    RETURNS
        (xmlnode *) DTD node

    ARGUMENTS
        ctx (IN) XML context

    SEE ALSO
	createDocumentType, createDocument, createDocumentNS, getDocTypeName,
	getDocTypeEntities, getDocTypeNotations
*/
xmlnode* getDocType(xmlctx *ctx);

/*---------------------------------------------------------------------------
    NAME
        getImplementation [DOM 1]

    FUNCTION
	Returns a DOM implementation structure

    DESCRIPTION
        Returns the DOM-implementation-specific descriptor.  Used to probe
	the implementation with hasFeature, or to create new Document or
	DTDs.

    RETURNS
        (xmldomimp *) DOM implementation

    ARGUMENTS
        ctx (IN) XML context

    SEE ALSO
	createDocument, createDocumentNS, createDocumentType, hasFeature
*/
xmldomimp* getImplementation(xmlctx *ctx);

/*---------------------------------------------------------------------------
    NAME
        getDocument [DOM X]

    FUNCTION
	Returns the Document node

    DESCRIPTION
        Returns the root node of the DOM tree, which is a Document node, or
	NULL if there is none.  The Document node is created automatically
	when a document is parsed successfully, or manually by createDocument
	or createDocumentNS.

    RETURNS
        (xmlnode *) Document node or NULL

    ARGUMENTS
        ctx (IN) XML context

    SEE ALSO
	createDocument, createDocumentNS
*/
xmlnode* getDocument(xmlctx *ctx);

/*---------------------------------------------------------------------------
    NAME
        getDocumentElement [DOM 1]

    FUNCTION
	Returns the root element node

    DESCRIPTION
        Returns the root element (node) of the DOM tree, or NULL if there
	is none.  Each document has only one uppermost Element node, called
	the root element.  It is created after a document is parsed
	successfully, or manually by createElement then appendChild, etc.

    RETURNS
        (xmlnode *) root element node or NULL

    ARGUMENTS
        ctx (IN) XML context

    SEE ALSO
	createElement
*/
xmlnode* getDocumentElement(xmlctx *ctx);

/*---------------------------------------------------------------------------
    NAME
        createElement [DOM 1]

    FUNCTION
	Creates an element node (non-namespace)

    DESCRIPTION
        Creates an element node with the given tag name (which should be in
	the data encoding).  Note that the tag name of an element is CASE
	SENSITIVE.  This is the non-namespace aware function: the new node
	will have NULL namespace URI and prefix, and its local name will be the
	same as its tag name, even if the tag name specified is a QName.  The
	new node is an orphan with no parent; it must be added to the DOM
	tree with appendChild etc.

    RETURNS
        (xmlnode *) new element node

    ARGUMENTS
        ctx     (IN) XML context
        tagName (IN) new element's name [in data encoding]

    SEE ALSO
	createElementNS
*/
xmlnode *createElement(xmlctx *ctx, const oratext *tagName);

/*---------------------------------------------------------------------------
    NAME
        createElementNS [DOM 2]

    FUNCTION
	Creates an element node (namespace-aware)

    DESCRIPTION
        Creates an element with the given namespace URI and QName.  Note
	that element names are CASE SENSITIVE, and the QName is required
	though the URI may be NULL.  The QName will be split into prefix and
	local parts, retrievable with getNodePrefix, getNodeLocal, etc;
	the tagName will be the full QName.  The new node is an orphan with
	no parent; it must be added to the DOM tree with appendChild etc.

    RETURNS
        (xmlnode *) new element node

    ARGUMENTS
        ctx   (IN) XML context
        uri   (IN) new element's namespace URI [in data encoding]
	qname (IN) new element's QName [in data encoding]

    SEE ALSO
	createElement
*/
xmlnode *createElementNS(xmlctx *ctx, const oratext *uri, const oratext*qname);

/*---------------------------------------------------------------------------
    NAME
        createDocumentFragment [DOM 1]

    FUNCTION
	Creates an empty document fragment node

    DESCRIPTION
        Creates an empty Document Fragment node.  A document fragment is
	treated specially when it is inserted into a DOM tree: the children
	of the fragment are inserted in order instead of the fragment node
	itself.  After insertion, the fragment node will still exist, but
	have no children.  See insertBefore, replaceChild, appendChild, etc.
	The name of a fragment node is always "#document-fragment".

    RETURNS
        (xmlnode *) new document fragment node

    ARGUMENTS
	ctx (IN) XML context

    SEE ALSO
	insertBefore, replaceChild, appendChild
*/
xmlnode *createDocumentFragment(xmlctx *ctx);

/*---------------------------------------------------------------------------
    NAME
        createTextNode [DOM 1]

    FUNCTION
	Creates a text node

    DESCRIPTION
        Creates a Text node with the given initial data (which must be
	non-NULL and in the data encoding).  The data may be NULL; if
	provided, it is not verified, converted, checked, or parsed
	(entities will not be expanded).  If bad data is set, bad things
	may happen-- GIGO!  The name of a fragment node is always "#text".
	New data for a Text node can be set with setNodeValue; see the
	CharacterData interface for editing methods.  The new node is
	an orphan with no parent; it must be added to the DOM tree with
	appendChild etc.

    RETURNS
        (xmlnode *) new Text node

    ARGUMENTS
        ctx  (IN) XML context
        data (IN) initial data [in data encoding] or NULL

    SEE ALSO
	setNodeValue, getNodeValue, setCharData, getCharData, getCharLength,
	substringData, appendData, insertData, deleteData, replaceData
*/
xmlnode *createTextNode(xmlctx *ctx, const oratext *data);

/*---------------------------------------------------------------------------
    NAME
        createComment [DOM 1]

    FUNCTION
	Creates a comment node

    DESCRIPTION
        Creates a Comment node with the given initial data (which must be
	in the data encoding).  The data may be NULL; if provided, it is not
	verified, converted, or checked.  If bad data is set, bad things may
	happen-- GIGO!  The name of a Comment node is always "#comment".  The
	new node is an orphan with no parent; it must be added to the DOM
	tree with appendChild etc.

    RETURNS
        (xmlnode *) new Comment node

    ARGUMENTS
        ctx  (IN) XML context
        data (IN) initial data [in data encoding] or NULL
*/
xmlnode *createComment(xmlctx *ctx, const oratext *data);

/*---------------------------------------------------------------------------
    NAME
        createCDATASection [DOM 1]

    FUNCTION
	Creates a CDATA node

    DESCRIPTION
        Creates a CDATASection node with the given initial data (which
	should be in the data encoding).  A CDATA section is considered
	verbatim and is never parsed; it will not be joined with adjacent
	Text nodes by the normalize operation.  The initial data may be
	NULL; if provided, it is not verified, converted, or checked.  If
	bad data is set, bad things may happen-- GIGO!  The name of a
	CDATA node is always "#cdata-section".  The new node is an orphan
	with no parent; it must be added to the DOM tree with appendChild etc.

    RETURNS
        (xmlnode *) new CDATA node

    ARGUMENTS
        ctx  (IN) XML context
        data (IN) initial data [in data encoding]

    SEE ALSO
	createTextNode
*/
xmlnode *createCDATASection(xmlctx *ctx, const oratext *data);

/*---------------------------------------------------------------------------
    NAME
        createProcessingInstruction [DOM 1]

    FUNCTION
	Creates a PI node

    DESCRIPTION
        Creates a Processing Instruction node with the given target and
	data (which should be in the data encoding).  The data may be NULL
	initially, and may be changed later (with setPIData), but the
	target is required and cannot be changed.  Note the target and data
	are not verified, converted, or checked.  If bad data is set, bad
	things may happen-- GIGO!  The name of a PI node is the same as the
	target.  The new node is an orphan with no parent; it must be added
	to the DOM tree with appendChild etc.

    RETURNS
        (xmlnode *) new PI node

    ARGUMENTS
        ctx    (IN) XML context
        target (IN) PI's target [in data encoding]
        data   (IN) PI's data [in data encoding] or NULL

    SEE ALSO
	getPITarget, getPIData, setPIData
*/
xmlnode *createProcessingInstruction(xmlctx *ctx, const oratext *target,
                                     const oratext *data);

/*---------------------------------------------------------------------------
    NAME
        createAttribute [DOM 1]

    FUNCTION
	Creates an attribute node (non-namespace)

    DESCRIPTION
        Creates an attribute node with the given name and value (in the
	data encoding).  Note this function differs from the DOM
	specification, which does not allow the initial value of the
	attribute to be set (see setAttrValue).  The name is required,
	but the value may be NULL; neither is verified, converted, or
	checked.  If bad data is set, bad things may happen-- GIGO!
	This is the non-namespace aware function (see createAttributeNS):
	the new attribute will have NULL namespace URI and prefix, and
	its local name will be the same as its name, even if the name
	specified is a QName.  See the Attr interface for more attribute
	manipulation methods.  If given an initial value, the attribute's
	specified flag will be TRUE.  The new node is an orphan with no
	parent; it must be added to the DOM tree with appendChild etc.
	See setAttribute which creates and adds an attribute in a single
	operation.

    RETURNS
        (xmlnode *) new attribute node

    ARGUMENTS
        ctx   (IN) XML context
        name  (IN) attribute's name [in data encoding]
        value (IN) attribute's value [in data encoding] or NULL

    SEE ALSO
	setAttrValue, createAttributeNS, setAttribute
*/
xmlnode *createAttribute(xmlctx *ctx, const oratext *name,
                         const oratext *value);

/*---------------------------------------------------------------------------
    NAME
        createAttributeNS [DOM 2]

    FUNCTION
	Creates an attribute node (namespace-aware)

    DESCRIPTION
        Creates an attribute node with the given namespace URI and QName;
	this is the namespace-aware version of createAttribute.  Note this
	function differs from the DOM specification, which does not allow
	the initial value of the attribute to be set (see setAttrValue).
	The name is required, but the value may be NULL; neither is verified,
	converted, or checked.  If bad data is set, bad things may happen--
	GIGO!   If given an initial value, the attribute's specified flag
	will be TRUE.  The new node is an orphan with no parent; it must
	be added to the DOM tree with appendChild etc.  See setAttribute
	which creates and adds an attribute in a single operation.

    RETURNS
        (xmlnode *) new attribute node

    ARGUMENTS
        ctx   (IN) XML context
        uri   (IN) attribute's namespace URI [in data encoding] or NULL
	qname (IN) attribute's qualified name [in data encoding]
        value (IN) attribute's initial value [in data encoding] or NULL

    SEE ALSO
	setAttrValue, createAttribute, setAttribute
*/
xmlnode *createAttributeNS(xmlctx *ctx, const oratext *uri,
                           const oratext *qname, const oratext *value);

/*---------------------------------------------------------------------------
    NAME
        createEntityReference [DOM 1]

    FUNCTION
	Creates an entity reference node

    DESCRIPTION
        Creates an Entity Reference node; the name (which should be in the
	data encoding) is the name of the entity to be referenced.  The named
	entity does not have to exist.  The name is not verified, converted,
	or checked.  If bad data is set, bad things may happen-- GIGO!   
	Entity Reference nodes are never generated by the parser; instead,
	entity references are expanded as encountered.  On output, an entity
	reference node will turn into a "&name;" style reference.  The new
	node is an orphan with no parent; it must be added to the DOM tree
	with appendChild etc.

    RETURNS
        (xmlnode *) new entity reference node

    ARGUMENTS
        ctx  (IN) XML context
        name (IN) name of referenced entity [in data encoding]
*/
xmlnode *createEntityReference(xmlctx *ctx, const oratext *name);

/*---------------------------------------------------------------------------
    NAME
        getElementsByTagName [DOM 1]

    FUNCTION
	Returns the elements matching a name (non-namespace)

    DESCRIPTION
	Returns a list of all elements (in the document tree rooted at the
	root node) with a given tag name, in the order in which they would
	be encountered in a preorder traversal of the tree.  If root is NULL,
	the entire document is searched.  The tag name should be in the data
	encoding.  The special name "*" matches all tag names; a NULL name
	matches nothing.  Note that tag names are CASE SENSITIVE.  This
	function is not namespace aware; the full tag names are compared.
	If two prefixes which map to the same URI are compared, the
	comparison will fail.  See getElementsByTagNameNS for the namespace-
	aware version.  The returned list can be freed with freeElements.

    RETURNS
        (xmlnodes *) list of matching nodes

    ARGUMENTS
        ctx     (IN) XML context
	root    (IN) root of search tree
        tagName (IN) tagName to match or "*" [in data encoding]

    SEE ALSO
	getElementsByTagNameNS, freeElements
*/
xmlnodes *getElementsByTagName(xmlctx *ctx, xmlnode *node,
                               const oratext *tagName);

/*---------------------------------------------------------------------------
    NAME
        getElementsByTagNameNS [DOM 2]

    FUNCTION
	Returns the elements matching a namespace URI and local

    DESCRIPTION
        Returns a list of all elements (in the document tree rooted at the
        given node) with a given namespace URI and local name, in the order
	in which they would be encountered in a preorder traversal of the
	tree.  If root is NULL, the entire document is searched.  The URI
	and local name should be in the data encoding.  The special local
	name "*" matches all local names; a NULL local name matches nothing.
	Namespace URIs must always match, however.  Note that comparisons
	are CASE SENSITIVE.  See getElementsByTagName for the non-namespace
	aware version.  The returned list can be freed with freeElements.

    RETURNS
        (xmlnodes *) list of nodes containing all the matched elements

    ARGUMENTS
        ctx   (IN) XML context
	root  (IN) root node
        uri   (IN) namespace URI [in data encoding]
        local (IN) namespace local name or "*" [in data encoding]

    SEE ALSO
	getElementsByTagName, freeElements
*/
xmlnodes *getElementsByTagNameNS(xmlctx *ctx, xmlnode *node,
                                 const oratext *uri, const oratext *local);

/*---------------------------------------------------------------------------
    NAME
        getElementByID [DOM 2]

    FUNCTION
	Returns the element with the given ID

    DESCRIPTION
        Returns the element node which has the given ID.  If no such ID is
        defined, returns NULL.  Note that attributes named "ID" are not
	automatically of type ID; ID attributes (which can have any name)
	must be declared as type ID in the DTD.

    RETURNS
        (xmlnode *) matching element node or NULL

    ARGUMENTS
        ctx (IN) XML context
        id  (IN) element ID [in data encoding]
*/
xmlnode *getElementByID(xmlctx *ctx, oratext *id);

/*---------------------------------------------------------------------------
    NAME
        importNode [DOM 2]

    FUNCTION
	Copies a node from one document to another

    DESCRIPTION
	Imports a node from one Document to another.  The new node is an
	orphan and has no parent; it must be added to the DOM tree with
	appendChild, etc.  The original node is not modified in any way
	or removed from its document; instead, a new node is created with
	copies of all the original node's QName, prefix, namespace URI,
	and local name.  As with cloneNode, the deep controls whether the
	children of the node are recursively imported.  If FALSE, only the
	node itself is imported, and it will have no children.  If TRUE,
	all descendents of the node will be imported as well, and an
	entire new subtree created.

	Document and DocumentType nodes cannot be imported.  Imported
	attributes will have their specified flags set to TRUE.  Elements
	will have only their specified attributes imported; non-specified
	(default) attributes are omitted.  New default attributes (for the
	destination document) are then added.

    RETURNS
        (xmlnode *) element node with given ID

    ARGUMENTS
        ctx    (IN) XML context
        import (IN) node to import
	deep   (IN) recursively import children?

    SEE ALSO
	cloneNode
*/
xmlnode *importNode(xmlctx *ctx, xmlnode *import, boolean deep);

/****************************************************************************
			    Interface NamedNodeMap
 ****************************************************************************/

/*---------------------------------------------------------------------------
    NAME
        getNamedItem [DOM 1]

    FUNCTION
	Returns an item from a node map by name

    DESCRIPTION
        Retrieves an item from a NamedNodeMap, specified by name (which
	should be in the data encoding).  This is a non-namespace-aware
	function; it just matches (case sensitively) on the whole QName.
	Note this function differs from the DOM spec in that the index
	of the matching item is also returned.  

    RETURNS
        (xmlnode *) matching node or NULL

    ARGUMENTS
        nodes (IN)  node map
        name  (IN)  name of node to retrieve [in data encoding]
        index (OUT) index of node, if found

    SEE ALSO
	setNamedItem, removeNamedItem, getChildNode
*/
xmlnode *getNamedItem(const xmlnodes *nodes, const oratext *name, 
                      size_t *index);

/*---------------------------------------------------------------------------
    NAME
	setNamedItem [DOM 1]

    FUNCTION
	Add a new item to a node map

    DESCRIPTION
	Adds a new node to a NamedNodeMap.  If a node already exists with
	the given name, replaces the old node and returns it.  If no such
	named node exists, adds the new node to the map and sets old to
	NULL.  This is a non-namespace-aware function; it just matches
	(case sensitively) on the whole QName.  Since some node types have
	fixed names (Text, Comment, etc), trying to set another of the same
	type will always cause replacement.

    RETURNS
	(boolean) success, node added or replaced

    ARGUMENTS
	ctx    (IN)  XML context
	nodes  (IN)  node map
	node   (IN)  new node to set
	old    (OUT) replaced node or NULL

    SEE ALSO
	getNamedItem, removeNamedItem
*/
boolean setNamedItem(xmlctx *ctx, xmlnodes *nodes,
                     xmlnode *node, xmlnode **old);

/*---------------------------------------------------------------------------
    NAME
        removeNamedItem [DOM 1]

    FUNCTION
	Removes an item from a node map by name

    DESCRIPTION
        Removes a node from a NamedNodeMap, specified by name.  This is a
	non-namespace-aware function; it just matches (case sensitively)
	on the whole QName.  If the removed node is an attribute with default
	value (not specified), it is immediately replaced.  The removed node
	is returned; if no removal took place, NULL is returned.

    RETURNS
        (xmlnode *) the removed node or NULL

    ARGUMENTS
        nodes (IN) node map
        name  (IN) name of node to remove [in data encoding]

    SEE ALSO
	getNamedItem, setNamedItem
*/
xmlnode *removeNamedItem(xmlnodes *nodes, const oratext *name);

/*---------------------------------------------------------------------------
    NAME
        getChildNode [DOM 1 item]

    FUNCTION
	Return an item from a node map by index

    DESCRIPTION
        Returns the indexth node in a NamedNodeMap, or NULL if there is no
	such node.  Indexes are zero-based, so the first node is index 0.

    RETURNS
        (xmlnode *) indexth node or NULL

    ARGUMENTS
        nodes (IN) node map
        index (IN) index of node to return (0-based)

    SEE ALSO
	getNamedItem
*/
xmlnode *getChildNode(const xmlnodes *nodes, size_t index);

/*---------------------------------------------------------------------------
    NAME
	getNodeMapLength [DOM 1 NamedNodeMap.length attribute]

    FUNCTION
	Returns the length of a node map

    DESCRIPTION
	Returns the number of nodes in a NamedNodeMap (the length).
	Note that nodes are referred to by index, and the range of
	valid indexes is 0 through length-1.

    RETURNS
	(size_t) number of nodes in map

    ARGUMENTS
	nodes (IN) node map

    SEE ALSO
	getChildNode
*/
size_t getNodeMapLength(const xmlnodes *nodes);

/****************************************************************************
			    Interface CharacterData
 ****************************************************************************/

/*---------------------------------------------------------------------------
    NAME
        getCharData [DOM 1 getData]

    FUNCTION
	Returns the data for a character node

    DESCRIPTION
        Returns the data for a CharacterData node (type Text, Comment or
	CDATASection) in the data encoding.  For other node types, or if
	there is no data, returns NULL.

    RETURNS
        (oratext *) node's data [in the data encoding]

    ARGUMENTS
        node (IN) node whose data to return

    SEE ALSO
	setCharData, createTextNode, createComment, createCDATASection
*/
const oratext *getCharData(const xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
	setCharData [DOM 1 setData]

    FUNCTION
	Sets the data for a character node

    DESCRIPTION
	Sets data for a CharacterData node (type Text, Comment or
	CDATASection), replacing the old data.  For other node types,
	does nothing.  The new data is not verified, converted, or
	checked-- it should be in the data encoding.  If bad data is
	set, bad things may happen-- GIGO!   

    RETURNS
	(void)

    ARGUMENTS
	node (IN) node whose data to set
	data (IN) new data for node [in data encoding]

    SEE ALSO
	getCharData
*/
void setCharData(xmlnode *node, const oratext *data);

/*---------------------------------------------------------------------------
    NAME
        getCharLength [DOM 1 getLength]

    FUNCTION
	Returns the length of a character node's data

    DESCRIPTION
        Returns the length of the data for a CharacterData node (type Text,
	Comment or CDATASection).  For other node types, returns 0.  Note
	the the data is the data encoding, and the returned length is in
	characters, not bytes.

    RETURNS
        (size_t) length of data [in characters]

    ARGUMENTS
        node (IN) node whose data length to return

    SEE ALSO
	getCharData
*/
size_t getCharLength(const xmlnode *node);

/*---------------------------------------------------------------------------
    NAME
        substringData [DOM 1]

    FUNCTION
	Returns a substring of a character node's data

    DESCRIPTION
        Returns a range of character data from a CharacterData node (type
	Text, Comment or CDATASection).  For other node types, or if count
	is zero, returns NULL.  Since the data is in the data encoding,
	offset and count are in characters, not bytes.  The beginning of
	the string is offset 0.  If the sum of offset and count exceeds the
	length, then all characters to the end of the data are returned.

    EXAMPLE
	Given a node with data "abcdefgh",
	substringData(offset=0, length=1) --> "a"
	substringData(offset=5, length=5) --> "fgh"

    RETURNS
        (oratext *) specified substring or NULL

    ARGUMENTS
        ctx    (IN) XML context
        node   (IN) node whose substring to extract
        offset (IN) starting offset of substring [zero based, in characters]
        count  (IN) length of substring [in characters]

    SEE ALSO
	appendData, insertData, deleteData, replaceData, splitText
*/
const oratext *substringData(xmlctx *ctx, const xmlnode *node,
                             ub4 offset, ub4 count);

/*---------------------------------------------------------------------------
    NAME
        appendData [DOM 1]

    FUNCTION
	Appends to a character node's data

    DESCRIPTION
        Append a string to the end of a CharacterData node's data.  If the
	node is not Text, Comment or CDATASection, or if the string to append
	is NULL, does nothing.  The appended data should be in the data
	encoding.  It will not be verified, converted, or checked.  If bad
	data is appended, bad things may happen-- GIGO!   

    RETURNS
        (void)

    ARGUMENTS
        ctx  (IN) XML context
        node (IN) node whose data to append to 
        arg  (IN) string to append [in data encoding]

    SEE ALSO
	getCharData, insertData, deleteData, replaceData, splitText
*/
void appendData(xmlctx *ctx, xmlnode *node, const oratext *arg);

/*---------------------------------------------------------------------------
    NAME
        insertData [DOM 1]

    FUNCTION
	Inserts into a character node's data

    DESCRIPTION
        Insert a string into a CharacterData node's data at the specified
	position.  If the node is not Text, Comment or CDATASection, or if
	the data to be inserted is NULL, or the offset is outside the
	original data, does nothing.  The inserted data must be in the
	data encoding.  It will not be verified, converted, or checked.
	If bad data is appended, bad things may happen-- GIGO!   The offset
	is specified as characters, not bytes.  The offset is zero-based,
	so inserting at offset zero prepends the data.

    EXAMPLE
	Given a node with data "abcdefgh",
	insertData(offset=0, arg="FOO") --> "FOOabcdefgh"
	insertData(offset=5, arg="*") --> "abcde*fgh"

    RETURNS
        (void)

    ARGUMENTS
        ctx    (IN) XML context
        node   (IN) node whose data to insert string to 
        offset (IN) offset at which to insert [in characters]
        arg    (IN) string to insert [in data encoding]

    SEE ALSO
	getCharData, appendData, deleteData, replaceData, splitText
*/
void insertData(xmlctx *ctx, xmlnode *node, ub4 offset, const oratext *arg);

/*---------------------------------------------------------------------------
    NAME
        deleteData [DOM 1]

    FUNCTION
	Removes part of a character node's data

    DESCRIPTION
        Remove a range of characters from a CharacterData node's data.
	If the node is not Text, Comment or CDATASection, or if the
	offset is outside of the original data, does nothing.  The offset
	is zero-based, so offset zero refers to the start of the data.
	Both offset and count are in characters, not bytes.  If the sum
	of offset and count exceeds the data length then all characters
	from offset to the end of the data are deleted.

    EXAMPLE
	Given a node with data "abcdefgh",
	deleteData(offset=0, count=2) --> "cdefgh"
	deleteData(offset=5, count=5) --> "abcde"

    RETURNS
        (void)

    ARGUMENTS
        ctx    (IN) XML context
        node   (IN) node whose data to delete string from
        offset (IN) offset to remove from [in characters]
        count  (IN) number of characters to remove

    SEE ALSO
	getCharData, appendData, insertData, replaceData, splitText
*/
void deleteData(xmlctx *ctx, xmlnode *node, ub4 offset, ub4 count);

/*---------------------------------------------------------------------------
    NAME
        replaceData [DOM 1]

    FUNCTION
	Replaces part of a character node's data

    DESCRIPTION
        Replaces a range of characters in a CharacterData node's data with
	a new string.  If the node is not Text, Comment or CDATASection, or
	if the offset is outside of the original data, or if the replacement
	string is NULL, does nothing.  If the count is zero, acts just as
	insertData.  The offset is zero-based, so offset zero refers to the
	start of the data.  The replacement data must be in the data encoding.
	It will not be verified, converted, or checked.  If bad data is set,
	bad things may happen-- GIGO!   The offset and count are both in
	characters, not bytes.  If the sum of offset and count exceeds
	length, then all characters to the end of the data are replaced.

    EXAMPLE
	Given a node with data "abcdefgh",
	replaceData(offset=0, count=1, arg="FOO") --> "FOObcdefgh"
	replaceData(offset=2, count=2, arg="*") --> "ab*efgh"
	replaceData(offset=5, count=5, arg="*") --> "abcde*"

    RETURNS
        (void)

    ARGUMENTS
        ctx    (IN) XML context
        node   (IN) node whose data to edit
        offset (IN) offset of original substring
        count  (IN) length of substring [in characters]
        arg    (IN) string to replace with [in data encoding]

    SEE ALSO
	getCharData, appendData, insertData, deleteData, splitText
*/
void replaceData(xmlctx *ctx, xmlnode *node, ub4 offset,
                 ub4 count, const oratext *arg);

/****************************************************************************
			    Interface Text
 ****************************************************************************/

/*---------------------------------------------------------------------------
    NAME
	splitText [DOM 1]

    FUNCTION
	Splits one text node into two

    DESCRIPTION
	Splits a single Text node into two Text nodes; the original data
	is split between them.  If the given node is not type Text, or the
	offset is outside of the original data, does nothing and returns
	NULL.  The offset is zero-based, and is in characters, not bytes.
	The original node is retained, its data is just truncated.  A new
	Text node is created which contains the remainder of the original
	data, and is inserted as the next sibling of the original.  The
	new Text node is returned.

    EXAMPLE
	Given a Text node with data "abcdefgh",
	splitText(1) --> Text("a"), Text("bcdefgh")
	splitText(5) --> Text("abcde"), Text("fgh")

    RETURNS
	(xmlnode *) new Text node or NULL

    ARGUMENTS
	ctx    (IN) XML context
	old    (IN) Text node to split
	offset (IN) split point [zero based]

    SEE ALSO
	getCharData, appendData, insertData, deleteData, replaceData
*/
xmlnode *splitText(xmlctx *ctx, xmlnode *old, uword offset);

/****************************************************************************
			    Interface DocumentType
 ****************************************************************************/

/*---------------------------------------------------------------------------
    NAME
	getDocTypeName [DOM 1 DocumentType.getName]

    FUNCTION
	Returns the name of a DTD

    DESCRIPTION
	Returns a DTD's name (specified immediately after the DOCTYPE
	keyword), or NULL if the node is not DocumentType.

    RETURNS
	(oratext *) name of DTD [in data encoding] or NULL

    ARGUMENTS
	node (IN) DTD node

    SEE ALSO
	getDocType, getDocTypeEntities, getDocTypeNotations, getContentModel
*/
const oratext *getDocTypeName(xmlnode* node);

/*---------------------------------------------------------------------------
    NAME
	getDocTypeEntities [DOM 1 DocumentType.getEntities]

    FUNCTION
	Returns a DTD's general entities

    DESCRIPTION
	Returns a NamedNodeMap of general entities defined by the DTD.
	If the node is not DocumentType, or has no general entities,
	returns NULL.  The nodes in the map will be of type Entity.

    RETURNS
	(xmlnodes *) pointer to (general) entities for DTD

    ARGUMENTS
	node (IN) map of DTD's entities

    SEE ALSO
	getDocType, getDocTypeName, getDocTypeNotations, getContentModel
*/
xmlnodes *getDocTypeEntities(xmlnode* node);

/*---------------------------------------------------------------------------
    NAME
	getDocTypeNotations [DOM 1 DocumentType.getNotations]

    FUNCTION
	Returns a DTD's notations

    DESCRIPTION
	Returns NamedNodeMap of notations declared by the DTD.  If the
	node is not DocumentType or has no notations, returns NULL.
	Nodes in the map will be of type Notation.

    RETURNS
	(xmlnodes *) map of DTD's notations

    ARGUMENTS
	node (IN) pointer to DTD node (as returned by getDocType)

    SEE ALSO
	getDocType, getDocTypeName, getDocTypeEntities, getContentModel
*/
xmlnodes *getDocTypeNotations(xmlnode* node);

/*---------------------------------------------------------------------------
    NAME
	getContentModel [DOM X]

    FUNCTION
	Returns the content model of the named element

    DESCRIPTION
	Returns the root node of the content model tree for a named
	element.  If an element by the given name does not exist,
	returns NULL.  The name must be in the data encoding, and is
	case sensitive.

	Nodes in the content model subtree will be one of the following
	Content Particle (CP) types: CP_ELEMENT_NODE, CP_CHOICE_NODE,
	CP_SEQUENCE_NODE, CP_PCDATA_NODE, CP_STAR_NODE, CP_PLUS_NODE,
	or CP_OPT_NODE

    RETURNS
	(xmlnode *) pointer to root CP node

    ARGUMENTS
	node (IN) DTD node
	name (IN) element's name [in data encoding]

    SEE ALSO
	getDocType, getDocTypeName, getDocTypeEntities, getDocTypeNotations
*/
xmlnode *getContentModel(xmlnode *node, oratext *name);

/****************************************************************************
			    Interface Notation
 ****************************************************************************/

/*---------------------------------------------------------------------------
    NAME
	getNotationPubID [DOM 1 Notation.publicId attribute]

    FUNCTION
	Returns the public ID of a notation

    DESCRIPTION
	Return a notation's public identifier (in the data encoding).  If
	the node is not a Notation, or has no defined public ID, returns NULL.

    RETURNS
	(oratext *) node's public ID [in data encoding] or NULL

    ARGUMENTS
	note (IN) Notation node

    SEE ALSO
	getNotationSysID
*/
const oratext *getNotationPubID(const xmlnode *note);

/*---------------------------------------------------------------------------
    NAME
	getNotationSysID [DOM 1 Notation.systemId attribute]

    FUNCTION
	Returns the system ID of a notation

    DESCRIPTION
	Return a notation's system identifier (in the data encoding).  If
	the node is not a Notation, or has no defined system ID, returns NULL.

    RETURNS
	(oratext *) node's system ID [in data encoding] or NULL

    ARGUMENTS
	note (IN) Notation node

    SEE ALSO
	getNotationPubID
*/
const oratext *getNotationSysID(const xmlnode *note);

/****************************************************************************
			    Interface Entity
 ****************************************************************************/

/*---------------------------------------------------------------------------
    NAME
	getEntityPubID [DOM 1 Entity.getPublicId]

    FUNCTION
	Returns the public ID of an entity

    DESCRIPTION
	Returns an entity's public identifier (in the data encoding).  If
	the node is not an Entity, or has no defined public ID, returns NULL.

    RETURNS
	(oratext *) entity's public ID [in data encoding] or NULL

    ARGUMENTS
	ent (IN) Entity node

    SEE ALSO
	getEntitySysID, getEntityNotation
*/
const oratext *getEntityPubID(const xmlnode *ent);

/*---------------------------------------------------------------------------
    NAME
	getEntitySysID [DOM 1 Entity.getSystemId]

    FUNCTION
	Returns the system ID of an entity

    DESCRIPTION
	Returns an entity's system identifier (in the data encoding).  If
	the node is not an Entity, or has no defined system ID, returns NULL.

    RETURNS
	(oratext *) entity's system ID [in data encoding] or NULL

    ARGUMENTS
	ent (IN) Entity node

    SEE ALSO
	getEntityPubID, getEntityNotation
*/
const oratext *getEntitySysID(const xmlnode *ent);

/*---------------------------------------------------------------------------
    NAME
	getEntityNotation [DOM 1 Entity.getNotationName]

    FUNCTION
	Returns the notation name of an entity

    DESCRIPTION
	For unparsed entities, returns the name of its notation (in the data
	encoding).  For parsed entities and other node types, returns NULL.

    RETURNS
	(oratext *) entity's NDATA [in data encoding] or NULL

    ARGUMENTS
	ent (IN) Entity node

    SEE ALSO
	getEntityPubID, getEntitySysID
*/
const oratext *getEntityNotation(const xmlnode *ent);

/****************************************************************************
			    Interface ProcessingInstruction
 ****************************************************************************/

/*---------------------------------------------------------------------------
    NAME
	getPITarget [DOM 1 ProcessingInstruction.getTarget]

    FUNCTION
	Returns the target of a PI

    DESCRIPTION
	Returns a Processing Instruction's (PI) target string.  If the
	node is not a PI, returns NULL.  The target is the first token
	following the markup that begins the PI.  All PIs must have a
	target, though the data part is optional.

    EXAMPLE
	<?rating extra saucy?>
	getPITarget --> "rating"

    RETURNS
	(oratext *) PI's target [in data encoding]

    ARGUMENTS
	pi (IN) PI node

    SEE ALSO
	getPIData, setPIData
*/
const oratext *getPITarget(const xmlnode *pi);

/*---------------------------------------------------------------------------
    NAME
	getPIData [DOM 1 ProcessingInstruction.getData]

    FUNCTION
	Returns the data of a PI

    DESCRIPTION
	Returns the content (data) of a Processing Instruction (in the data
	encoding).  If the node is not a PI, returns NULL.  The content is
	the part from the first non-whitespace character after the target
	until the ending "?>".

    EXAMPLE
	<?rating extra saucy?>
	getPIData --> "extra saucy"

    RETURNS
	(oratext *) PI's data [in data encoding]

    ARGUMENTS
	pi (IN) PI node

    SEE ALSO
	setPIData, getPITarget
*/
const oratext *getPIData(const xmlnode *pi);

/*---------------------------------------------------------------------------
    NAME
	setPIData [DOM 1 ProcessingInstruction.setData]

    FUNCTION
	Sets the data of a PI

    DESCRIPTION
	Set's a Processing Instruction's (PI) data (content), which must be
	in the data encoding.  It is not permitted to set the data to NULL.
	If the node is not a PI, does nothing.  The new data is not verified,
	converted, or checked.  If bad data is set, bad things may happen--
	GIGO!

    RETURNS
	(void)

    ARGUMENTS
	pi   (IN) PI node
	data (IN) new content [in data encoding]

    SEE ALSO
	getPIData, getPITarget
*/
void setPIData(xmlnode *pi, const oratext *data);

/*---------------------------------------------------------------------------
                      Package XSLT - XSLT and XPath APIs

    A software module called an XSL processor is used to read XML documents
    and transform them into other XML documents with different styles.

    The C implementation of the XSL processor follows the XSL Transformations 
    standard (version 1.0, November 16, 1999) and implements the required
    behavior of an XSL processor as specified in the XSLT specification.

  ---------------------------------------------------------------------------*/

/****************************************************************************
			    Interface XSLProcessor
 ****************************************************************************/

/*---------------------------------------------------------------------------
    NAME
        xslprocess

    FUNCTION
	Process XSL

    DESCRIPTION
        This function processes XSL Stylesheet with XML document source.
        Since this function returns a DOM document fragment node, it doesn't 
        support xsl:output.  To use xsl:output, call xslsetoutputstream and
        xslprocessxml.

    RETURNS
        (uword) error code, XMLERR_OK [0] on success

    ARGUMENTS
        xmlctx (I/O) XML document context
        xsl    (IN)  XSL stylesheet context
        resctx (IN)  result document fragment context        
        result (I/O) result document fragment node
*/
uword xslprocess(xmlctx *docctx, xmlctx *xsl,
                 xmlctx *resctx, xmlnode **result);

/*---------------------------------------------------------------------------
    NAME
        xslprocessex

    FUNCTION
        Process XSL

    DESCRIPTION
        This function processes XSL Stylesheet with XML document source.
        User can specify a list of top-level parameters to be set before
        parsing begins.  Since this function returns a DOM document fragment 
        node, it doesn't support xsl:output.  To use xsl:output, call 
        xslsetoutputstream and xslprocessxml.

    RETURNS
        (uword) error code, XMLERR_OK [0] on success

    ARGUMENTS
        xmlctx  (I/O) XML document context
        xsl     (IN)  XSL stylesheet context
        resctx  (IN)  result document fragment context
        nparams (IN)  number of [params,vals] pairs to be passed
        params  (IN)  array of name of pars [must be nparams in count]
        vals    (IN)  array of value of pars [must be nparams in count]
        baseuri (IN)  string giving the base uri for style sheet
        result  (I/O) result document fragment node
*/
uword xslprocessex(xmlctx *docctx, xmlctx *xsl, xmlctx *resctx,
                   size_t nparams, oratext * params[], oratext * vals[],
                   oratext * baseuri, xmlnode **result);

/*---------------------------------------------------------------------------
    NAME
        xslinit

    FUNCTION
        Initialize XSL context

    DESCRIPTION
        This routine is used to create the XSL processing context to 
        process one or more input XML DOM tree (specified through a 
        XML context). This context holds all the variables, states 
        and global parameters required to process a given XML DOM 
        tree. Depending on the choice of the user, processing can 
        generate its output in any one of following 3 forms: SAX  
        based events, a stream output or a DOM tree. During the 
        processing of the input XSL stylesheet is translated in to 
        an internal format and stored in xslctx.  This transformation 
        is done on as is needed basis and can be used again during 
        subsequent processing if the same xslctx is used again. 
        Hence the user can create a single xslctx for a stylesheet 
        which is being used again and again and cache it to speedup
        processing of successive input XML trees which are using 
        same XSL stylesheet again and again. The caching will
        ensure the usage of already translated intermediate format 
        of the XSL stylesheet available from a prior processing,
        instead of need to generate it again.

    RETURNS
        (xslctx *) pointer to new XSL context, or NULL

    ARGUMENTS
        err    (OUT) error code, XMLERR_OK [0] on success
        xsl    (IN)  XNL context of the input stylesheet
        baseURI(IN)  base URI for include and import statements
        resvd  (IN)  reserved for future use [must be set to 0]
*/
xslctx *xslinit(uword *err, xmlctx *xsl, const oratext *baseURI, ub4 resvd);

/*---------------------------------------------------------------------------
    NAME
        xslgetbaseuri

    FUNCTION
        Get base URI associated with XSL context

    DESCRIPTION
        Get base URI associated with XSL context

    RETURNS
        (const oratext *) base URI or NULL.

    ARGUMENTS
        xslSSctx (IN) the XSL processing context to be inquired upon
*/
const oratext *xslgetbaseuri(xslctx *xslSSctx);

/*---------------------------------------------------------------------------
    NAME
        xslgetxslctx

    FUNCTION
        Get the input stylesheet DOM context with XSL context

    DESCRIPTION
        Get XML context for XSL stylesheet associated with XSL context

    RETURNS
        (xmlctx *) XML context if successful, or NULL.

    ARGUMENTS
        xslSSctx (IN) the XSL processing context to be inquired upon
*/
xmlctx *xslgetxslctx(xslctx *xslSSctx);

/*---------------------------------------------------------------------------
    NAME
        xslsettextparam

    FUNCTION
        Set a top-level XSL parameter

    DESCRIPTION
        xslsettextparam is used to create a top level parameter 
        (or variable) to be used during the subsequent processing
        of XML DOM trees. User can call it any number of times, 
        to set as many variables as he wants. A subsequent call 
        with preexisting parameter name will override the old 
        value with the new value supplied. User can use the
        xslgettextparam to inquire the value of a preexisting 
        variable. A value specified to be NULL will reset
        the variable as if it was never added.

    RETURNS
        (uword) error code, XMLERR_OK [0] on success

    ARGUMENTS
        xslSSctx   (IN) XSL processing context 
        param_name (IN) name of parameter [variable] to be set.
        param_val  (IN) parameter value the parameter is to be set to. 
*/
uword xslsettextparam(xslctx *xslSSctx, const oratext *param_name, 
                      const oratext *param_value);

/*---------------------------------------------------------------------------
    NAME
        xslgettextparam

    FUNCTION
        Enquire about the preexisting top level parameter or value

    DESCRIPTION
        Given the parameter pull up the current value it is set to.

    RETURNS
        (const oratext *) String giving parameter value, or NULL

    ARGUMENTS
        xslSSctx   (IN) XSL processing context to be inquired upon
        param_name (IN) parameter whose value is to be inquired.
*/
const oratext *xslgettextparam(xslctx *xslSSctx, const oratext *param_name);

/*---------------------------------------------------------------------------
    NAME
       xslresetallparams

    FUNCTION
       Reset all the top level XSL parameters added

    DESCRIPTION
       Reset all the top level XSL parameters added

    RETURNS
       (uword) error code, XMLERR_OK [0] on success

    ARGUMENTS
        xslSSctx (IN) the XSL processing context to be inquired upon
*/
uword xslresetallparams(xslctx *xslSSctx);

/*---------------------------------------------------------------------------
    NAME
       xslsetoutputmethod

    FUNCTION
       Set overriding XSL output method

    DESCRIPTION
       This call is used to set an output method equivalent to XSL 
       processing direction <xsl:output method = "text/xml/html">.
       If the xsl stylesheet contains one or more similar statements 
       then this function will override the effect of any previously
       present statements in XSL stylesheet.

    RETURNS
       (uword) error code, XMLERR_OK [0] on success

    ARGUMENTS
        xslSSctx (IN) XSL processing context
        method   (IN) selected output method
        resvd    (IN) reserved for future use [must be set to 0]
*/
uword xslsetoutputmethod(xslctx *xslSSctx, xsloutputmethod method, ub4 resvd);

/*---------------------------------------------------------------------------
    NAME
       xslsetoutputencoding

    FUNCTION
       Set encoding for XSL output

    DESCRIPTION
       This call is used to set an output method equivalent to XSL 
       processing direction <xsl:output encoding = ".....">.
       If the xsl stylesheet contains one or more similar statements 
       then this function will override the effect of any previously
       present statements in XSL stylesheet.

    RETURNS
       (uword) error code, XMLERR_OK [0] on success

    ARGUMENTS
        xslSSctx  (IN) XSL processing context
        outcoding (IN) output encoding name
*/
uword xslsetoutputencoding(xslctx *xslSSctx, oratext *outcoding);

/*---------------------------------------------------------------------------
    NAME
	xslsetoutputdomctx

    FUNCTION
	Set XML context for storing XSL processing result

    DESCRIPTION
        xslsetoutputdomctx  is used for setting the xmlctx which will be
	used to store the output DOM tree.  A call to xslsetoutputdomctx
	overrides any previous output method set using any previous calls
	to xslsetoutputdomctx or xslsetoutputstream or xslsetoutputsax.
	Any subsequent processing of the XML input will be stored in form
	of a Document fragment in xmlctx specified by resctx.
	xslgetoutputdomctx can be used to inquire presently set resctx.
	If no DOM context is set or a call to xslsetoutputdomctx has been
	overridden by a subsequent call to xslsetoutputstream or 
        xslsetoutputsax then xslgetoutputdomctx will return NULL context
	indicating that present output mode is not a DOM output mode.

    RETURNS
        (uword) error code, XMLERR_OK [0] on success

    ARGUMENTS
        xslSSctx (IN) XSL processing context
        resCtx   (IN) XML context for output document fragment 
*/
uword xslsetoutputdomctx(xslctx *xslSSctx, xmlctx *resctx);

/*---------------------------------------------------------------------------
    NAME
        xslgetoutputdomctx

    FUNCTION
        Returns XML context for storing XSL output

    DESCRIPTION
        Returns the XML context set by a previous call to 
        xslsetoutputdomctx.

    RETURNS
        (xmlctx *) XML context if successful, Otherwise returns NULL.

    ARGUMENTS
        xslSSctx (IN) XSL processing context
*/
xmlctx *xslgetoutputdomctx(xslctx *xslSSctx);

/*---------------------------------------------------------------------------
    NAME 
	xslsetoutputstream

    FUNCTION 
	DEPRECATED Set the XSL output stream

    DESCRIPTION
        DEPRECATED - DO NOT USE THIS FUNCTION FOR NEW WORK.  ALL STREAMING
        CODE SHOULD USE THE NEW orastream STRUCTURE DEFINED IN orastruc.h
        xslsetoutputstream is used for setting the xmlstream to be 
        used for redirecting the text output of the XSL processing. A 
        call to xslsetoutputstream  overrides any previous output 
        method set using any previous calls to xslsetoutputdomctx 
        or xslsetoutputstream or xslsetoutputsax.  Any subsequent 
        processing of the XML input will be redirected in text format to
        the callbacks specified by stream. xslgetoutputstream  can be 
        used to inquire presently set stream. If no output stream is set 
        or a call to xslsetoutputstream  has been overridden by a 
        subsequent call to xslsetoutputdomctx or xslsetoutputsax  
        then xslgetoutputstream  will return NULL indicating that 
        present output mode is not a stream based output 
        mode.

    RETURNS
        (uword) error code, XMLERR_OK [0] on success

    ARGUMENTS
        xslSSctx (IN) XSL processing context
        stream   (IN) stream structure
*/
uword xslsetoutputstream(xslctx *xslSSctx, xmlstream *stream);

/*---------------------------------------------------------------------------
    NAME 
	xslsetoutputorastream

    FUNCTION 
	Set the XSL output orastream

    DESCRIPTION
        xslsetoutputstream is used for setting the orastream to be 
        used for redirecting the text output of the XSL processing. A 
        call to xslsetoutputstream  overrides any previous output 
        method set using any previous calls to xslsetoutputdomctx 
        or xslsetoutputstream or xslsetoutputsax.  Any subsequent 
        processing of the XML input will be redirected in text format to
        the callbacks specified by stream. xslgetoutputstream  can be 
        used to inquire presently set stream. If no output stream is set 
        or a call to xslsetoutputstream  has been overridden by a 
        subsequent call to xslsetoutputdomctx or xslsetoutputsax  
        then xslgetoutputstream  will return NULL indicating that 
        present output mode is not a stream based output mode.

    RETURNS
        (uword) error code, XMLERR_OK [0] on success

    ARGUMENTS
        xslSSctx (IN) XSL processing context
        stream   (IN) orastream structure
*/
uword xslsetoutputorastream(xslctx *xslSSctx, orastream *ostream);

/*---------------------------------------------------------------------------
    NAME
        xslgetoutputstream

    FUNCTION
        Returns the XSL output stream

    DESCRIPTION
        Returns the xmlstream set by a previous call to xslsetoutputstream

    RETURNS
        (xmlstream *) stream or NULL.

    ARGUMENTS
        xslSSctx (IN) XSL processing context
*/
xmlstream *xslgetoutputstream(xslctx *xslSSctx);

/*---------------------------------------------------------------------------
    NAME
        xslgetoutputorastream

    FUNCTION
        Returns the XSL output orastream

    DESCRIPTION
        Returns the orastream set by a previous call to xslsetoutputorastream

    RETURNS
        (orastream *) stream or NULL.

    ARGUMENTS
        xslSSctx (IN) XSL processing context
*/
orastream *xslgetoutputorastream(xslctx *xslSSctx);

/*---------------------------------------------------------------------------
    NAME
	xslsetoutputsax

    FUNCTION
        Sets the SAX based events to be generated

    DESCRIPTION
        Sets the SAX callback structure which describes SAX event to be
	be invoked as the processing progresses to generate output nodes.
	The context to be passed to the SAX event handler is set with a
	call to xslsetoutputsaxctx (or the context will be NULL).

	A call to xslsetoutputsax overrides any previous output method 
        set using any previous calls to xslsetoutputdomctx or 
        xslsetoutputstream or xslsetoutputsax.  Any subsequent processing
	of the XML input will generate SAX events specified by the SAX
	context.  xslgetoutputsax can be used to inquire presently set SAX
	context. If no SAX context is set or a call to xslsetoutputsax has
	been overridden by a subsequent call to xslsetoutputdomctx or 
        xslsetoutputstream then xslgetoutputsax will return NULL indicating
	that present output mode is not a SAX based output mode.

        Note: User can make a call to xslsetoutputsaxctx to set the SAX
	context to be used by the SAX callbacks. If none is set, then a NULL
	will be passed to the SAX callbacks as SAX context.

        Also note that just setting the callbacks is sufficient to invoke
	the SAX callbacks.

    RETURNS
        (uword) error code, XMLERR_OK [0] on success

    ARGUMENTS
        xslSSctx (IN) XSL processing context to be inquired upon
        s        (IN) SAX callbacks structure

    SEE ALSO
	xslsetoutputsaxctx
*/
uword xslsetoutputsax(xslctx *xslSSctx, xmlsaxcb *s);

/*---------------------------------------------------------------------------
    NAME
	xslsetoutputsaxctx

    FUNCTION
        Sets the context for SAX events

    DESCRIPTION
	Sets the context to be passed to SAX event handlers.  If not
	specified, it will be NULL.

    RETURNS
        (uword) error code, XMLERR_OK [0] on success

    ARGUMENTS
        xslSSctx (IN) XSL processing context to be inquired upon
	ctx      (IN) user-defined SAX context

    SEE ALSO
	xslsetoutputsax
*/
uword xslsetoutputsaxctx(xslctx *xslSSctx, void *ctx);

/*---------------------------------------------------------------------------
    NAME
        xslgetoutputsax

    FUNCTION
	Returns SAX callbacks

    DESCRIPTION
        Returns the xmlsaxcbset by a previous call to xslsetoutputsax.

    RETURNS
        (xmlsaxcb *) SAX callback structure or NULL

    ARGUMENTS
        xslSSctx (IN) XSL processing context
*/
xmlsaxcb *xslgetoutputsax(xslctx *xslSSctx);

/*---------------------------------------------------------------------------
    NAME
        xslprocessxml

    FUNCTION
	Processes XML

    DESCRIPTION
        Once user have created the xslctx (the XSL processing context 
        using LpxXSLCreatCtx), have set the base URI, set all the top 
        level parameters (using one or more calls to xslsettextparam),
        have selected an output method (using one of the calls to 
        xslsetoutputdomctx or xslsetoutputstream or 
        xslsetoutputsax).. .. .. then this is the function call to 
        make to carry out all the action. This function will process 
        the given XML file (specified by its DOM context) according to 
        the XSL stylesheet, parameters and, output method set in the 
        xslctx. Once this call returns, depending on the output scheme 
        which user might have selected:

	For Stream based output:
	    The output text has been redirected using the stream callbacks.

	For SAX based output:
	    User would have already got all the SAX events executed.

	For DOM based output:
	    User can make a call to xslgetresultdocfrag function to 
	    access the final Document Fragment created in context of
	    the resCtx set by a call to xslsetoutputdomctx.

        The XSL processor expects a normalized DOM tree as an input.  If
	user is not sure whether the XML tree is normalized or not, then
	he should set this flag to TRUE and this call will normalize the DOM;
	Otherwise set it to FALSE.

        xsl:output is supported only for stream based output.

    RETURNS
        (uword) error code, XMLERR_OK [0] on success

    ARGUMENTS
        xslSSctx  (IN) XSL processing context
        xmlCtx    (IN) XML context of the input XML tree
        normalize (IN) normalize input document?
	resvd     (IN) reserved for future use [must be set to 0]
*/
uword xslprocessxml(xslctx *xslSSctx, xmlctx *xmlctx, 
                    boolean normalize, ub4 resvd);

/*---------------------------------------------------------------------------
    NAME
        xslprocessxmldocfrag

    FUNCTION
	Processs an XML document fragment

    DESCRIPTION
        Once user have created the xslctx (the XSL processing context 
        using LpxXSLCreatCtx), have set the base URI, set all the top 
        level parameters (using one or more calls to xslsettextparam),
        have selected an output method (using one of the calls to 
        xslsetoutputdomctx or xslsetoutputstream or 
        xslsetoutputsax).. .. .. then this is the function call to 
        make to carry out all the action. This function will process 
        the given XML document fragment according to the XSL stylesheet, 
        parameters and, output method set in the xslctx. Once this call 
        returns, depending on the output scheme which user might have 
        selected:

	For Stream based output:
	    The output text has been redirected using the stream callbacks.

	For SAX based output:
	    User would have already got all the SAX events executed.

	For DOM based output:
	    User can make a call to xslgetresultdocfrag function to 
	    access the final Document Fragment created in context of
	    the resCtx set by a call to xslsetoutputdomctx.

        The XSL processor expects a normalized DOM tree as an input.  If
	user is not sure whether the XML tree is normalized or not, then
	he should set this flag to TRUE and this call will normalize the DOM;
	Otherwise set it to FALSE.

        xsl:output is supported only for stream based output.

    RETURNS
        (uword) error code, XMLERR_OK [0] on success

    ARGUMENTS
        xslSSctx  (IN) XSL processing context
        xmlCtx    (IN) XML context for the input XML Doc Frag
        docFrag   (IN) document fragment
        normalize (IN) normalize input document?
        resvd     (IN) reserved for future use [must be set to 0]
*/
uword xslprocessxmldocfrag(xslctx *xslSSctx, xmlctx *xmlctx, xmlnode *docFrag,
                           boolean normalize, /* ARGUSED */ ub4 resvd);

/*---------------------------------------------------------------------------
    NAME
        xslgetresultdocfrag

    FUNCTION
	Gets resulting document fragment

    DESCRIPTION
        This function should be called after a call to xslprocessxml  
        for the DOM based output method. If the output method for the 
        last call to xslprocessxml was DOM based, this function will 
        return the Document Fragment created by XSL processing of the 
        given XML tree, otherwise this function will return NULL 
        indicating that the output method selected was not DOM based or 
        no XML processing has been carried out since either the creation 
        of xslSSctx or since last selecting an output method for the 
        specified xslctx.

    RETURNS
        (xmlnode *) resulting DOM tree.

    ARGUMENTS
        xslSSctx (IN) XSL processing context
*/
xmlnode *xslgetresultdocfrag(xslctx *xslSSctx);

/*---------------------------------------------------------------------------
    NAME
        xslterm

    FUNCTION
	Terminates XSL context

    DESCRIPTION
        This function will terminate the XSL context and free all the
        intermediate data structures created for it during any previous
        processing using this context. Once terminated, the XSL context
        is no more valid and must not be used any further.

    RETURNS
        (uword) error code, XMLERR_OK [0] on success

    ARGUMENTS
        xslSSctx (IN) XSL processing context
*/
uword xslterm(xslctx *xslSSctx);

/****************************************************************************
			    Interface XPath
 ****************************************************************************/

/*---------------------------------------------------------------------------
    NAME
	xpmakexpathctx

    FUNCTION
	Makes an XPath context

    DESCRIPTION
	Creates, initializes and returns an XPath context.  The XPath
	context makes use of an internally created dummy XSL and XML
	context. When you are done executing the XPath related function
	calls, free this context with xpfreexpathctx.

	If ctx is NULL, we internally create a dummy xml context.  This
	context is used to obtain the encoding, memory management, access
	routines and error handlers.

	If xslnode is NULL, no name space expansion will be done at the
	time of parsing.  xml_node should be NULL for parsing.  baseURI
	sets the base URI for document function calls which might be
	made internally.  Set nctxels to the number of context nodes to
	follow (or 0 if no context list is available).

    RETURNS
	(xpctx *) the created XPath context

    ARGUMENTS
	ctx      (IN) XML parser context
	xslnode  (IN) XSL node used for namespace expansion
	xml_node (IN) context node for expression evaluation.
	baseURI  (IN) base URI for document
	nctxels  (IN) number of context nodes to follow
	ctxnodes (IN) array of nctxels nodes

    SEE ALSO
	xpfreexpathctx
*/
xpctx *xpmakexpathctx(xmlctx *ctx, xmlnode *xslnode,
                      xmlnode *xml_node, oratext *baseURI,
                      size_t nctxels, xmlnode **ctxnodes);

/*---------------------------------------------------------------------------
    NAME
	xpfreexpathctx

    FUNCTION
	Frees an XPath context

    DESCRIPTION
	Frees an XPath context allocated by a prior call to xpmakexpathctx.
	Once freed the xctx pointer is no more valid and must not be used
	further.

    RETURNS
	(void)

    ARGUMENTS
	xctx (I/O) XPath context to be freed.

    SEE ALSO
	xpmakexpathctx
*/
void xpfreexpathctx(xpctx *xctx);

/*---------------------------------------------------------------------------
    NAME
	xpparsexpathexpr

    FUNCTION
	Parses an XPath expression

    DESCRIPTION
	Take an expression in the form of a string and parses it.  The
	result is in the form of an expression tree.  The encoding should
	be in the data encoding.

    RETURNS
	(xpexpr *) expression tree or NULL

    ARGUMENTS
	xctx (I/O) XPath context
	expr (IN)  expression [in data encoding]
	err  (OUT) error code, XMLERR_OK [0] on success

    SEE ALSO
	xpevalxpathexpr
*/
xpexpr *xpparsexpathexpr(xpctx *xctx, oratext *expr, sword *err);

/*---------------------------------------------------------------------------
    NAME
	xpevalxpathexpr

    FUNCTION
	Evaluates an XPath expression

    DESCRIPTION
	Evaluates the previously parsed expression and returns the result.
	The exprtree is obtained by making a call to xpparsexpathexpr to parse
	the given XPath expression string.

    RETURNS
	(xpobj *) result object or NULL

    ARGUMENTS
	xctx (I/O) XPath context
	expr (IN)  parsed expression.
	err  (OUT) error code, XMLERR_OK [0] on success

    SEE ALSO
	xpparsexpathexpr
*/
xpobj *xpevalxpathexpr(xpctx *xctx, xpexpr *exprtree, sword *err);

/*---------------------------------------------------------------------------
    NAME
	xpgetxpobjtyp

    FUNCTION
	Returns the type code of an XPath object

    DESCRIPTION
	Returns the type code of an XPath object

    RETURNS
	(xpobjtyp) object type

    ARGUMENTS
	xobj (IN) XPath object

    SEE ALSO
	xpgetbooleanval, xpgetnumval, xpgetstrval, xpgetnsetval, xpgetrtfragval
*/
xpobjtyp xpgetxpobjtyp(xpobj * xobj);

/*---------------------------------------------------------------------------
    NAME
	xpgetbooleanval

    FUNCTION
	Returns the value of a boolean XPath object

    DESCRIPTION
	For bool XPath object (type XPOBJTYP_BOOL), returns its
	boolean value, TRUE or FALSE.

    RETURNS
	(boolean) boolean object's value

    ARGUMENTS
	xobj (IN) XPath object

    SEE ALSO
	xpgetnumval, xpgetstrval, xpgetnsetval, xpgetrtfragval
*/
boolean xpgetbooleanval(xpobj *xobj);

/*---------------------------------------------------------------------------
    NAME
	xpgetnumval

    FUNCTION
	Returns the value of a numeric XPath object

    DESCRIPTION
	For numeric XPath objects (type XPOBJTYP_NUM), returns its
	numeric value

    RETURNS
	(double) numeric object's value

    ARGUMENTS
	xobj (IN) XPath object

    SEE ALSO
	xpgetbooleanval, xpgetstrval, xpgetnsetval, xpgetrtfragval
*/
double xpgetnumval(xpobj *xobj);

/*---------------------------------------------------------------------------
    NAME
	xpgetstrval

    FUNCTION
	Returns the value of a string XPath object

    DESCRIPTION
	For string-type XPath objects (type XPOBJTYP_STR), returns
	its string value.

    RETURNS
	(oratext *) string object's value

    ARGUMENTS
	xobj (IN) XPath object

    SEE ALSO
	xpgetbooleanval, xpgetnumval, xpgetnsetval, xpgetrtfragval
*/
oratext *xpgetstrval(xpobj *xobj);

/*---------------------------------------------------------------------------
    NAME
	xpgetnsetval

    FUNCTION
	Returns the node-set of a node-set XPath object

    DESCRIPTION
	For node-set XPath objects (type XPOBJTYP_NSET), returns
	its node-set value.

    EXAMPLE
	nsetval = xpgetnsetval(xobj);
	for (nsetele = xpgetfirstnsetelem(nsetval);
	     nsetelem; nsetelem = xpgetnextnsetelem(nsetval))
	{
	    node = xpgetnsetelemnode(nsetele);
	    ....use node ...
	}

    RETURNS
	(xpnset *) XPath object's node-set value

    ARGUMENTS
	xobj (IN) XPath object

    SEE ALSO
	xpgetfirstnsetelem, xpgetnextnsetelem, xpgetnsetelemnode
*/
xpnset *xpgetnsetval(xpobj *xobj);

/*---------------------------------------------------------------------------
    NAME
	xpgetfirstnsetelem

    FUNCTION
	Returns first element in a node-set

    DESCRIPTION
	Returns first element in a node-set.  See xpgetnsetval for
	typical usage.

    RETURNS
	(xpnsetele *) node-set element

    ARGUMENTS
	nset (IN) XPath node-set

    SEE ALSO
	xpgetnextnsetelem, xpgetnsetelemnode
*/
xpnsetele *xpgetfirstnsetelem(xpnset *nset);

/*---------------------------------------------------------------------------
    NAME
	xpgetnextnsetelem

    FUNCTION
	Returns next element in a node-set

    DESCRIPTION
	Returns next element in a node-set, given an element in that
	node-set.  See xpgetnsetval for sample usage.

    RETURNS
	(xpnsetele *) next node-set element

    ARGUMENTS
	nsetele (IN) current node-set element

    SEE ALSO
	xpgetfirstnsetelem, xpgetnsetelemnode
*/
xpnsetele *xpgetnextnsetelem(xpnsetele *nsetele);

/*---------------------------------------------------------------------------
    NAME
	xpgetnsetelemnode

    FUNCTION
	Returns the XML node for a node-set element

    DESCRIPTION
	Returns the XML node corresponding to a node-set element.  See
	xpgetnsetval for sample usage.

    RETURNS
	(xmlnode *) XML node

    ARGUMENTS
	nsetele (IN) node-set element

    SEE ALSO
	xpgetfirstnsetelem, xpgetnextnsetelem, xpgetnsetelemnode
*/
xmlnode *xpgetnsetelemnode(xpnsetele *nsetele);

/*---------------------------------------------------------------------------
    NAME
	xpgetrtfragval

    FUNCTION
	Returns the XML node of a result-tree fragment

    DESCRIPTION
	Returns the XML node corresponding to a result-tree fragment
	XPath object (type XPOBJTYP_RTFRAG).

    RETURNS
	(xmlnode *) XML node

    ARGUMENTS
	xobj (IN) XPath object
*/
xmlnode *xpgetrtfragval(xpobj *xobj);

#endif  /* ORAXML_ORACLE */
